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

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

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

<dependency>
    <groupId>javax.el</groupId>
    <artifactId>javax.el-api</artifactId>
    <version>2.2.4</version>
</dependency>
<dependency>
    <groupId>org.glassfish.web</groupId>
    <artifactId>javax.el</artifactId>
    <version>2.2.4</version>
</dependency>

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

grant codeBase "file:path/to/hibernate-validator-5.3.6.Final.jar" {
    permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
    permission java.lang.RuntimePermission "accessDeclaredMembers";
    permission java.lang.RuntimePermission "setContextClassLoader";

    permission org.hibernate.validator.HibernateValidatorPermission "accessPrivateMembers";

    // Only needed when working with XML descriptors (validation.xml or XML constraint mappings)
    permission java.util.PropertyPermission "mapAnyUriToUri", "read";
};

grant codeBase "file:path/to/validation-api-1.1.0.Final.jar" {
    permission java.io.FilePermission "path/to/hibernate-validator-5.3.6.Final.jar", "read";
};

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

package org.hibernate.validator.referenceguide.chapter01;

import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;

public class Car {

    @NotNull
    private String manufacturer;

    @NotNull
    @Size(min = 2, max = 14)
    private String licensePlate;

    @Min(2)
    private int seatCount;

    public Car(String manufacturer, String licencePlate, int seatCount) {
        this.manufacturer = manufacturer;
        this.licensePlate = licencePlate;
        this.seatCount = seatCount;
    }

    //getters and setters ...
}

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:

package org.hibernate.validator.referenceguide.chapter01;

import java.util.Set;
import javax.validation.ConstraintViolation;
import javax.validation.Validation;
import javax.validation.Validator;
import javax.validation.ValidatorFactory;

import org.junit.BeforeClass;
import org.junit.Test;

import static org.junit.Assert.assertEquals;

public class CarTest {

    private static Validator validator;

    @BeforeClass
    public static void setUpValidator() {
        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        validator = factory.getValidator();
    }

    @Test
    public void manufacturerIsNull() {
        Car car = new Car( null, "DD-AB-123", 4 );

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

        assertEquals( 1, constraintViolations.size() );
        assertEquals( "may not be null", constraintViolations.iterator().next().getMessage() );
    }

    @Test
    public void licensePlateTooShort() {
        Car car = new Car( "Morris", "D", 4 );

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

        assertEquals( 1, constraintViolations.size() );
        assertEquals(
                "size must be between 2 and 14",
                constraintViolations.iterator().next().getMessage()
        );
    }

    @Test
    public void seatCountTooLow() {
        Car car = new Car( "Morris", "DD-AB-123", 1 );

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

        assertEquals( 1, constraintViolations.size() );
        assertEquals(
                "must be greater than or equal to 2",
                constraintViolations.iterator().next().getMessage()
        );
    }

    @Test
    public void carIsValid() {
        Car car = new Car( "Morris", "DD-AB-123", 2 );

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

        assertEquals( 0, constraintViolations.size() );
    }
}

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 Chapter 13, Further reading.

To learn more about the validation of beans and properties, just continue reading Chapter 2, Declaring and validating bean constraints. If you are interested in using Bean Validation for the validation of method pre- and postcondition refer to Chapter 3, Declaring and validating method constraints. In case your application has specific validation requirements have a look at Chapter 6, 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:

package org.hibernate.validator.referenceguide.chapter02.fieldlevel;

public class Car {

	@NotNull
	private String manufacturer;

	@AssertTrue
	private boolean isRegistered;

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

	//getters and setters...
}

package org.hibernate.validator.referenceguide.chapter02.propertylevel;

public class Car {

	private String manufacturer;

	private boolean isRegistered;

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

	@NotNull
	public String getManufacturer() {
		return manufacturer;
	}

	public void setManufacturer(String manufacturer) {
		this.manufacturer = manufacturer;
	}

	@AssertTrue
	public boolean isRegistered() {
		return isRegistered;
	}

	public void setRegistered(boolean isRegistered) {
		this.isRegistered = isRegistered;
	}
}

package org.hibernate.validator.referenceguide.chapter02.typeargument;

public class Car {

	@Valid
	private List<@ValidPart String> parts = new ArrayList<>();

	public void addPart(String part) {
		parts.add( part );
	}

	//...
}

Car car = Car();
car.addPart( "Wheel" );
car.addPart( null );

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

assertEquals( 1, constraintViolations.size() );
assertEquals(
		"'null' is not a valid car part.",
		constraintViolations.iterator().next().getMessage()
);
assertEquals( "parts[1].<collection element>",
		constraintViolations.iterator().next().getPropertyPath().toString() );

package org.hibernate.validator.referenceguide.chapter02.typeargument;

public class Car {

	public static enum FuelConsumption {
		CITY,
		HIGHWAY
	}

	@Valid
	private EnumMap<FuelConsumption, @MaxAllowedFuelConsumption Integer> fuelConsumption = new EnumMap<>( FuelConsumption.class );

	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() );
assertEquals( "20 is outside the max fuel consumption.", constraintViolations.iterator().next().getMessage() );

package org.hibernate.validator.referenceguide.chapter02.typeargument;

import java.util.ArrayList;
import java.util.EnumMap;
import java.util.List;
import java.util.Optional;
import javax.validation.Valid;

public class Car {

	private Optional<@MinTowingCapacity(1000) Integer> towingCapacity = Optional.empty();

	public void setTowingCapacity(Integer alias) {
		towingCapacity = Optional.of( alias );
	}

    //...
}

Car car = Car();
car.setTowingCapacity( 100 );

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

assertEquals( 1, constraintViolations.size() );
assertEquals( "Not enough towing capacity.", constraintViolations.iterator().next().getMessage() );
assertEquals( "towingCapacity", constraintViolations.iterator().next().getPropertyPath().toString() );

package org.hibernate.validator.referenceguide.chapter02.typeargument;

public class Car {

	private GearBox<@MinTorque(100) Gear> gearBox;

	public void setGearBox(GearBox<Gear> gearBox) {
		this.gearBox = gearBox;
	}

	//...
}

package org.hibernate.validator.referenceguide.chapter02.typeargument;

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.typeargument;

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

package org.hibernate.validator.referenceguide.chapter02.typeargument;

public class GearBoxUnwrapper extends ValidatedValueUnwrapper<GearBox> {
	@Override
	public Object handleValidatedValue(GearBox gearBox) {
		return gearBox == null ? null : gearBox.getGear();
	}

	@Override
	public Type getValidatedValueType(Type valueType) {
		return Gear.class;
	}
}

Car car = Car();
car.setGearBox( new GearBox<>( new Gear.AcmeGear() ) );

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

package org.hibernate.validator.referenceguide.chapter02.classlevel;

@ValidPassengerCount
public class Car {

	private int seatCount;

	private List<Person> passengers;

	//...
}

package org.hibernate.validator.referenceguide.chapter02.inheritance;

public class Car {

	private String manufacturer;

	@NotNull
	public String getManufacturer() {
		return manufacturer;
	}

	//...
}

package org.hibernate.validator.referenceguide.chapter02.inheritance;

public class RentalCar extends Car {

	private String rentalStation;

	@NotNull
	public String getRentalStation() {
		return rentalStation;
	}

	//...
}

package org.hibernate.validator.referenceguide.chapter02.objectgraph;

public class Car {

	@NotNull
	@Valid
	private Person driver;

	//...
}

package org.hibernate.validator.referenceguide.chapter02.objectgraph;

public class Person {

	@NotNull
	private String name;

	//...
}

package org.hibernate.validator.referenceguide.chapter02.objectgraph.list;

public class Car {

	@NotNull
	@Valid
	private List<Person> passengers = new ArrayList<Person>();

	//...
}

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.

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

Car car = new Car( null, true );

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

assertEquals( 1, constraintViolations.size() );
assertEquals( "may not be null", constraintViolations.iterator().next().getMessage() );

Car car = new Car( null, true );

Set<ConstraintViolation<Car>> constraintViolations = validator.validateProperty(
		car,
		"manufacturer"
);

assertEquals( 1, constraintViolations.size() );
assertEquals( "may not be null", constraintViolations.iterator().next().getMessage() );

Set<ConstraintViolation<Car>> constraintViolations = validator.validateValue(
		Car.class,
		"manufacturer",
		null
);

assertEquals( 1, constraintViolations.size() );
assertEquals( "may not be null", constraintViolations.iterator().next().getMessage() );
---

Hibernate Validator comprises a basic set of commonly used constraints. These are foremost the constraints defined by the Bean Validation specification (see Table 2.2, “Bean Validation constraints”). Additionally, Hibernate Validator provides useful custom constraints (see Table 2.3, “Custom constraints” and Table 2.4, “Custom country specific constraints”).

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

In Section 3.2.1, “Obtaining an ExecutableValidator instance” you will learn how to obtain an ExecutableValidator instance while Section 3.2.2, “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.

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

package org.hibernate.validator.referenceguide.chapter03.validation;

public class Car {

	public Car(@NotNull String manufacturer) {
		//...
	}

	@ValidRacingCar
	public Car(String manufacturer, String team) {
		//...
	}

	public void drive(@Max(75) int speedInMph) {
		//...
	}

	@Size(min = 1)
	public List<Passenger> getPassengers() {
		//...
	}
}

Car object = new Car( "Morris" );
Method method = Car.class.getMethod( "drive", int.class );
Object[] parameterValues = { 80 };
Set<ConstraintViolation<Car>> violations = executableValidator.validateParameters(
		object,
		method,
		parameterValues
);

assertEquals( 1, violations.size() );
Class<? extends Annotation> constraintType = violations.iterator()
		.next()
		.getConstraintDescriptor()
		.getAnnotation()
		.annotationType();
assertEquals( Max.class, constraintType );

Car object = new Car( "Morris" );
Method method = Car.class.getMethod( "getPassengers" );
Object returnValue = Collections.<Passenger>emptyList();
Set<ConstraintViolation<Car>> violations = executableValidator.validateReturnValue(
		object,
		method,
		returnValue
);

assertEquals( 1, violations.size() );
Class<? extends Annotation> constraintType = violations.iterator()
		.next()
		.getConstraintDescriptor()
		.getAnnotation()
		.annotationType();
assertEquals( Size.class, constraintType );

Constructor<Car> constructor = Car.class.getConstructor( String.class );
Object[] parameterValues = { null };
Set<ConstraintViolation<Car>> violations = executableValidator.validateConstructorParameters(
		constructor,
		parameterValues
);

assertEquals( 1, violations.size() );
Class<? extends Annotation> constraintType = violations.iterator()
		.next()
		.getConstraintDescriptor()
		.getAnnotation()
		.annotationType();
assertEquals( NotNull.class, constraintType );

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

Car object = new Car( "Morris" );
Method method = Car.class.getMethod( "drive", int.class );
Object[] parameterValues = { 80 };
Set<ConstraintViolation<Car>> violations = executableValidator.validateParameters(
		object,
		method,
		parameterValues
);

assertEquals( 1, violations.size() );
Iterator<Node> propertyPath = violations.iterator()
		.next()
		.getPropertyPath()
		.iterator();

MethodNode methodNode = propertyPath.next().as( MethodNode.class );
assertEquals( "drive", methodNode.getName() );
assertEquals( Arrays.<Class<?>>asList( int.class ), methodNode.getParameterTypes() );

ParameterNode parameterNode = propertyPath.next().as( ParameterNode.class );
assertEquals( "arg0", parameterNode.getName() );
assertEquals( 0, parameterNode.getParameterIndex() );

In addition to the built-in bean and property-level constraints discussed in Section 2.3, “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 Section 8.2.4, “ParameterNameProvider”). Example 3.17, “Using @ParameterScriptAssert” shows how the validation logic of the @LuggageCountMatchesPassengerCount constraint from Example 3.2, “Declaring a cross-parameter constraint” could be expressed with the help of @ParameterScriptAssert.

package org.hibernate.validator.referenceguide.chapter03.parametersscriptassert;

public class Car {

	@ParameterScriptAssert(lang = "javascript", script = "arg1.size() <= arg0.size() * 2")
	public void load(List<Person> passengers, List<PieceOfLuggage> luggage) {
		//...
	}
}

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 Example 4.1, “Specifying a message descriptor using the message attribute”.

package org.hibernate.validator.referenceguide.chapter04;

public class Car {

	@NotNull(message = "The manufacturer name must not be null")
	private String manufacturer;

	//constructor, getters and setters ...
}

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:

package org.hibernate.validator.referenceguide.chapter04.complete;

public class Car {

	@NotNull
	private String manufacturer;

	@Size(min = 2,
		max = 14,
		message = "The license plate '${validatedValue}' must be between {min} and {max} characters long"
	)
	private String licensePlate;

	@Min(value = 2,
		message = "There must be at least {value} seat${value > 1 ? 's' : ''}"
	)
	private int seatCount;

	@DecimalMax(value = "350",
			message = "The top speed ${formatter.format('%1$.2f', validatedValue)} is higher " +
					"than {value}"
	)
	private double topSpeed;

	@DecimalMax(value = "100000", message = "Price must not be higher than ${value}")
	private BigDecimal price;

	public Car(
			String manufacturer,
			String licensePlate,
			int seatCount,
			double topSpeed,
			BigDecimal price) {
		this.manufacturer = manufacturer;
		this.licensePlate = licensePlate;
		this.seatCount = seatCount;
		this.topSpeed = topSpeed;
		this.price = price;
	}

	//getters and setters ...
}

Car car = new Car( null, "A", 1, 400.123456, BigDecimal.valueOf( 200000 ) );

String message = validator.validateProperty( car, "manufacturer" )
		.iterator()
		.next()
		.getMessage();
assertEquals( "may not be null", message );

message = validator.validateProperty( car, "licensePlate" )
		.iterator()
		.next()
		.getMessage();
assertEquals(
		"The license plate must be between 2 and 14 characters long",
		message
);

message = validator.validateProperty( car, "seatCount" ).iterator().next().getMessage();
assertEquals( "There must be at least 2 seats", message );

message = validator.validateProperty( car, "topSpeed" ).iterator().next().getMessage();
assertEquals( "The top speed 400.12 is higher than 350", message );

message = validator.validateProperty( car, "price" ).iterator().next().getMessage();
assertEquals( "Price must not be higher than $100000", message );

If the default message interpolation algorithm does not fit your requirements it is also possible 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 Section 7.1, “Configuring the validator factory in validation.xml”) or by passing it when bootstrapping a ValidatorFactory or Validator (see Section 8.2.1, “MessageInterpolator” and Section 8.3, “Configuring a Validator”, respectively).

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

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

Groups allow you to restrict the set of constraints applied during validation. One use case 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 5.1, “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.

package org.hibernate.validator.referenceguide.chapter05;

public class Person {

	@NotNull
	private String name;

	public Person(String name) {
		this.name = name;
	}

	// getters and setters ...
}

The class Driver in Example 5.2, “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.

package org.hibernate.validator.referenceguide.chapter05;

public class Driver extends Person {

	@Min(
			value = 18,
			message = "You have to be 18 to drive a car",
			groups = DriverChecks.class
	)
	public int age;

	@AssertTrue(
			message = "You first have to pass the driving test",
			groups = DriverChecks.class
	)
	public boolean hasDrivingLicense;

	public Driver(String name) {
		super( name );
	}

	public void passedDrivingTest(boolean b) {
		hasDrivingLicense = b;
	}

	public int getAge() {
		return age;
	}

	public void setAge(int age) {
		this.age = age;
	}
}

package org.hibernate.validator.referenceguide.chapter05;

public interface DriverChecks {
}

Finally the class Car (Example 5.3, “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.

package org.hibernate.validator.referenceguide.chapter05;

public class Car {
	@NotNull
	private String manufacturer;

	@NotNull
	@Size(min = 2, max = 14)
	private String licensePlate;

	@Min(2)
	private int seatCount;

	@AssertTrue(
			message = "The car has to pass the vehicle inspection first",
			groups = CarChecks.class
	)
	private boolean passedVehicleInspection;

	@Valid
	private Driver driver;

	public Car(String manufacturer, String licencePlate, int seatCount) {
		this.manufacturer = manufacturer;
		this.licensePlate = licencePlate;
		this.seatCount = seatCount;
	}

	// getters and setters ...
}

package org.hibernate.validator.referenceguide.chapter05;

public interface CarChecks {
}

Overall three different groups are used in the example:

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

// create a car and check that everything is ok with it.
Car car = new Car( "Morris", "DD-AB-123", 2 );
Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );
assertEquals( 0, constraintViolations.size() );

// but has it passed the vehicle inspection?
constraintViolations = validator.validate( car, CarChecks.class );
assertEquals( 1, constraintViolations.size() );
assertEquals(
		"The car has to pass the vehicle inspection first",
		constraintViolations.iterator().next().getMessage()
);

// let's go to the vehicle inspection
car.setPassedVehicleInspection( true );
assertEquals( 0, validator.validate( car, CarChecks.class ).size() );

// now let's add a driver. He is 18, but has not passed the driving test yet
Driver john = new Driver( "John Doe" );
john.setAge( 18 );
car.setDriver( john );
constraintViolations = validator.validate( car, DriverChecks.class );
assertEquals( 1, constraintViolations.size() );
assertEquals(
		"You first have to pass the driving test",
		constraintViolations.iterator().next().getMessage()
);

// ok, John passes the test
john.passedDrivingTest( true );
assertEquals( 0, validator.validate( car, DriverChecks.class ).size() );

// just checking that everything is in order now
assertEquals(
		0, validator.validate(
		car,
		Default.class,
		CarChecks.class,
		DriverChecks.class
).size()
);

The first validate() call in Example 5.4, “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.

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

package org.hibernate.validator.referenceguide.chapter05;

@GroupSequence({ Default.class, CarChecks.class, DriverChecks.class })
public interface OrderedChecks {
}

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

Car car = new Car( "Morris", "DD-AB-123", 2 );
car.setPassedVehicleInspection( true );

Driver john = new Driver( "John Doe" );
john.setAge( 18 );
john.passedDrivingTest( true );
car.setDriver( john );

assertEquals( 0, validator.validate( car, OrderedChecks.class ).size() );

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 Example 5.10, “@ConvertGroup usage”. Here @GroupSequence({ CarChecks.class, Car.class }) is used to combine the car related constraints under the Default group (see Section 5.3, “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.

package org.hibernate.validator.referenceguide.chapter05.groupconversion;

public class Driver {

	@NotNull
	private String name;

	@Min(
			value = 18,
			message = "You have to be 18 to drive a car",
			groups = DriverChecks.class
	)
	public int age;

	@AssertTrue(
			message = "You first have to pass the driving test",
			groups = DriverChecks.class
	)
	public boolean hasDrivingLicense;

	public Driver(String name) {
		this.name = name;
	}

	public void passedDrivingTest(boolean b) {
		hasDrivingLicense = b;
	}

	// getters and setters ...
}

package org.hibernate.validator.referenceguide.chapter05.groupconversion;

@GroupSequence({ CarChecks.class, Car.class })
public class Car {

	@NotNull
	private String manufacturer;

	@NotNull
	@Size(min = 2, max = 14)
	private String licensePlate;

	@Min(2)
	private int seatCount;

	@AssertTrue(
			message = "The car has to pass the vehicle inspection first",
			groups = CarChecks.class
	)
	private boolean passedVehicleInspection;

	@Valid
	@ConvertGroup(from = Default.class, to = DriverChecks.class)
	private Driver driver;

	public Car(String manufacturer, String licencePlate, int seatCount) {
		this.manufacturer = manufacturer;
		this.licensePlate = licencePlate;
		this.seatCount = seatCount;
	}

	// getters and setters ...
}

As a result the validation in Example 5.11, “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.

// create a car and validate. The Driver is still null and does not get validated
Car car = new Car( "VW", "USD-123", 4 );
car.setPassedVehicleInspection( true );
Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );
assertEquals( 0, constraintViolations.size() );

// create a driver who has not passed the driving test
Driver john = new Driver( "John Doe" );
john.setAge( 18 );

// now let's add a driver to the car
car.setDriver( john );
constraintViolations = validator.validate( car );
assertEquals( 1, constraintViolations.size() );
assertEquals(
		"The driver constraint should also be validated as part of the default group",
		constraintViolations.iterator().next().getMessage(),
		"You first have to pass the driving test"
);

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:

package org.hibernate.validator.referenceguide.chapter06;

public enum CaseMode {
	UPPER,
	LOWER;
}

package org.hibernate.validator.referenceguide.chapter06;

@Target({ FIELD, METHOD, PARAMETER, ANNOTATION_TYPE })
@Retention(RUNTIME)
@Constraint(validatedBy = CheckCaseValidator.class)
@Documented
public @interface CheckCase {

	String message() default "{org.hibernate.validator.referenceguide.chapter06.CheckCase." +
			"message}";

	Class<?>[] groups() default { };

	Class<? extends Payload>[] payload() default { };

	CaseMode value();

	@Target({ FIELD, METHOD, PARAMETER, ANNOTATION_TYPE })
	@Retention(RUNTIME)
	@Documented
	@interface List {
		CheckCase[] value();
	}
}

package org.hibernate.validator.referenceguide.chapter06;

public class CheckCaseValidator implements ConstraintValidator<CheckCase, String> {

	private CaseMode caseMode;

	@Override
	public void initialize(CheckCase constraintAnnotation) {
		this.caseMode = constraintAnnotation.value();
	}

	@Override
	public boolean isValid(String object, ConstraintValidatorContext constraintContext) {
		if ( object == null ) {
			return true;
		}

		if ( caseMode == CaseMode.UPPER ) {
			return object.equals( object.toUpperCase() );
		}
		else {
			return object.equals( object.toLowerCase() );
		}
	}
}

package org.hibernate.validator.referenceguide.chapter06.constraintvalidatorcontext;

public class CheckCaseValidator implements ConstraintValidator<CheckCase, String> {

	private CaseMode caseMode;

	@Override
	public void initialize(CheckCase constraintAnnotation) {
		this.caseMode = constraintAnnotation.value();
	}

	@Override
	public boolean isValid(String object, ConstraintValidatorContext constraintContext) {
		if ( object == null ) {
			return true;
		}

		boolean isValid;
		if ( caseMode == CaseMode.UPPER ) {
			isValid = object.equals( object.toUpperCase() );
		}
		else {
			isValid = object.equals( object.toLowerCase() );
		}

		if ( !isValid ) {
			constraintContext.disableDefaultConstraintViolation();
			constraintContext.buildConstraintViolationWithTemplate(
					"{org.hibernate.validator.referenceguide.chapter03." +
					"constraintvalidatorcontext.CheckCase.message}"
			)
			.addConstraintViolation();
		}

		return isValid;
	}
}

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

package org.hibernate.validator.referenceguide.chapter06;

public class Car {

	@NotNull
	private String manufacturer;

	@NotNull
	@Size(min = 2, max = 14)
	@CheckCase(CaseMode.UPPER)
	private String licensePlate;

	@Min(2)
	private int seatCount;

	public Car ( String manufacturer, String licencePlate, int seatCount ) {
		this.manufacturer = manufacturer;
		this.licensePlate = licencePlate;
		this.seatCount = seatCount;
	}

	//getters and setters ...
}

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

//valid license plate
car = new Car( "Morris", "DD-AB-123", 4 );

constraintViolations = validator.validate( car );

assertEquals( 0, constraintViolations.size() );

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

package org.hibernate.validator.referenceguide.chapter06.classlevel;

@Target({ TYPE, ANNOTATION_TYPE })
@Retention(RUNTIME)
@Constraint(validatedBy = { ValidPassengerCountValidator.class })
@Documented
public @interface ValidPassengerCount {

	String message() default "{org.hibernate.validator.referenceguide.chapter06.classlevel." +
			"ValidPassengerCount.message}";

	Class<?>[] groups() default { };

	Class<? extends Payload>[] payload() default { };
}

package org.hibernate.validator.referenceguide.chapter06.classlevel;

public class ValidPassengerCountValidator
		implements ConstraintValidator<ValidPassengerCount, Car> {

	@Override
	public void initialize(ValidPassengerCount constraintAnnotation) {
	}

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

		return car.getPassengers().size() <= car.getSeatCount();
	}
}

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.

package org.hibernate.validator.referenceguide.chapter06.custompath;

public class ValidPassengerCountValidator
		implements ConstraintValidator<ValidPassengerCount, Car> {

	@Override
	public void initialize(ValidPassengerCount constraintAnnotation) {
	}

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

		boolean isValid = car.getPassengers().size() <= car.getSeatCount();

		if ( !isValid ) {
			constraintValidatorContext.disableDefaultConstraintViolation();
			constraintValidatorContext
					.buildConstraintViolationWithTemplate( "{my.custom.template}" )
					.addPropertyNode( "passengers" ).addConstraintViolation();
		}

		return isValid;
	}
}

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:

package org.hibernate.validator.referenceguide.chapter06.crossparameter;

@Constraint(validatedBy = ConsistentDateParameterValidator.class)
@Target({ METHOD, CONSTRUCTOR, ANNOTATION_TYPE })
@Retention(RUNTIME)
@Documented
public @interface ConsistentDateParameters {

	String message() default "{org.hibernate.validator.referenceguide.chapter06." +
			"crossparameter.ConsistentDateParameters.message}";

	Class<?>[] groups() default { };

	Class<? extends Payload>[] payload() default { };
}

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 Example 6.11, “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 Section 6.4, “Constraint composition”).

package org.hibernate.validator.referenceguide.chapter06.crossparameter;

@SupportedValidationTarget(ValidationTarget.PARAMETERS)
public class ConsistentDateParameterValidator implements
		ConstraintValidator<ConsistentDateParameters, Object[]> {

	@Override
	public void initialize(ConsistentDateParameters constraintAnnotation) {
	}

	@Override
	public boolean isValid(Object[] value, ConstraintValidatorContext context) {
		if ( value.length != 2 ) {
			throw new IllegalArgumentException( "Illegal method signature" );
		}

		//leave null-checking to @NotNull on individual parameters
		if ( value[0] == null || value[1] == null ) {
			return true;
		}

		if ( !( value[0] instanceof Date ) || !( value[1] instanceof Date ) ) {
			throw new IllegalArgumentException(
					"Illegal method signature, expected two " +
							"parameters of type Date."
			);
		}

		return ( (Date) value[0] ).before( (Date) value[1] );
	}
}

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 Example 6.12, “Generic and cross-parameter constraint”.

package org.hibernate.validator.referenceguide.chapter06.crossparameter;

@Constraint(validatedBy = {
		ScriptAssertObjectValidator.class,
		ScriptAssertParametersValidator.class
})
@Target({ TYPE, FIELD, PARAMETER, METHOD, CONSTRUCTOR, ANNOTATION_TYPE })
@Retention(RUNTIME)
@Documented
public @interface ScriptAssert {

	String message() default "{org.hibernate.validator.referenceguide.chapter06." +
			"crossparameter.ScriptAssert.message}";

	Class<?>[] groups() default { };

	Class<? extends Payload>[] payload() default { };

	String script();

	ConstraintTarget validationAppliesTo() default ConstraintTarget.IMPLICIT;
}

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 Example 6.13, “Specifying the target for a generic and cross-parameter constraint”.

@ScriptAssert(script = "arg1.size() <= arg0", validationAppliesTo = ConstraintTarget.PARAMETERS)
public Car buildCar(int seatCount, List<Passenger> passengers) {
	//...
}

Looking at the licensePlate field of the Car class in Example 6.6, “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. Example 6.14, “Creating a composing constraint @ValidLicensePlate” shows a composed constraint annotation which comprises the constraints @NotNull, @Size and @CheckCase:

package org.hibernate.validator.referenceguide.chapter06.constraintcomposition;

@NotNull
@Size(min = 2, max = 14)
@CheckCase(CaseMode.UPPER)
@Target({ METHOD, FIELD, ANNOTATION_TYPE })
@Retention(RUNTIME)
@Constraint(validatedBy = { })
@Documented
public @interface ValidLicensePlate {

	String message() default "{org.hibernate.validator.referenceguide.chapter06." +
			"constraintcomposition.ValidLicensePlate.message}";

	Class<?>[] groups() default { };

	Class<? extends Payload>[] payload() default { };
}

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:

package org.hibernate.validator.referenceguide.chapter06.constraintcomposition;

public class Car {

	@ValidLicensePlate
	private String licensePlate;

	//...
}

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:

//...
@ReportAsSingleViolation
public @interface ValidLicensePlate {

	String message() default "{org.hibernate.validator.referenceguide.chapter06." +
			"constraintcomposition.ValidLicensePlate.message}";

	Class<?>[] groups() default { };

	Class<? extends Payload>[] payload() default { };
}

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. Figure 7.1, “Validation configuration schema” shows a model view of the XML schema to which validation.xml has to adhere.

Figure 7.1. Validation configuration schema

Example 7.1, “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 Section 8.2, “Configuring a ValidatorFactory”.

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

    <default-provider>com.acme.ValidationProvider</default-provider>

    <message-interpolator>com.acme.MessageInterpolator</message-interpolator>
    <traversable-resolver>com.acme.TraversableResolver</traversable-resolver>
    <constraint-validator-factory>
        com.acme.ConstraintValidatorFactory
    </constraint-validator-factory>
    <parameter-name-provider>com.acme.ParameterNameProvider</parameter-name-provider>

    <executable-validation enabled="true">
        <default-validated-executable-types>
            <executable-type>CONSTRUCTORS</executable-type>
            <executable-type>NON_GETTER_METHODS</executable-type>
            <executable-type>GETTER_METHODS</executable-type>
        </default-validated-executable-types>
    </executable-validation>

    <constraint-mapping>META-INF/validation/constraints-car.xml</constraint-mapping>

    <property name="hibernate.validator.fail_fast">false</property>
</validation-config>

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 Section 8.2, “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 Chapter 3, 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 Section 11.2, “Fail fast mode”).

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

Figure 7.2. Validation mapping schema

Example 7.2, “Bean constraints configured via XML” shows how the classes Car and RentalCar from Example 5.3, “Car” resp. Example 5.7, “Class RentalCar with redefined default group” could be mapped in XML.

<constraint-mappings
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/mapping validation-mapping-1.1.xsd"
    xmlns="http://jboss.org/xml/ns/javax/validation/mapping" version="1.1">

    <default-package>org.hibernate.validator.referenceguide.chapter05</default-package>
    <bean class="Car" ignore-annotations="true">
        <field name="manufacturer">
            <constraint annotation="javax.validation.constraints.NotNull"/>
        </field>
        <field name="licensePlate">
            <constraint annotation="javax.validation.constraints.NotNull"/>
        </field>
        <field name="seatCount">
            <constraint annotation="javax.validation.constraints.Min">
                <element name="value">2</element>
            </constraint>
        </field>
        <field name="driver">
            <valid/>
        </field>
        <getter name="passedVehicleInspection" ignore-annotations="true">
            <constraint annotation="javax.validation.constraints.AssertTrue">
                <message>The car has to pass the vehicle inspection first</message>
                <groups>
                    <value>CarChecks</value>
                </groups>
                <element name="max">10</element>
            </constraint>
        </getter>
    </bean>
    <bean class="RentalCar" ignore-annotations="true">
        <class ignore-annotations="true">
            <group-sequence>
                <value>RentalCar</value>
                <value>CarChecks</value>
            </group-sequence>
        </class>
    </bean>
    <constraint-definition annotation="org.mycompany.CheckCase">
        <validated-by include-existing-validators="false">
            <value>org.mycompany.CheckCaseValidator</value>
        </validated-by>
    </constraint-definition>
</constraint-mappings>

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

<constraint-mappings
        xmlns="http://jboss.org/xml/ns/javax/validation/mapping"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation=
                "http://jboss.org/xml/ns/javax/validation/mapping validation-mapping-1.1.xsd" version="1.1">

    <default-package>org.hibernate.validator.referenceguide.chapter07</default-package>

    <bean class="RentalStation" ignore-annotations="true">
        <constructor>
            <return-value>
                <constraint annotation="ValidRentalStation"/>
            </return-value>
        </constructor>

        <constructor>
            <parameter type="java.lang.String">
                <constraint annotation="javax.validation.constraints.NotNull"/>
            </parameter>
        </constructor>

        <method name="getCustomers">
            <return-value>
                <constraint annotation="javax.validation.constraints.NotNull"/>
                <constraint annotation="javax.validation.constraints.Size">
                    <element name="min">1</element>
                </constraint>
            </return-value>
        </method>

        <method name="rentCar">
            <parameter type="Customer">
                <constraint annotation="javax.validation.constraints.NotNull"/>
            </parameter>
            <parameter type="java.util.Date">
                <constraint annotation="javax.validation.constraints.NotNull"/>
                <constraint annotation="javax.validation.constraints.Future"/>
            </parameter>
            <parameter type="int">
                <constraint annotation="javax.validation.constraints.Min">
                    <element name="value">1</element>
                </constraint>
            </parameter>
        </method>
    </bean>

    <bean class="Garage" ignore-annotations="true">
        <method name="buildCar">
            <parameter type="java.util.List"/>
            <cross-parameter>
                <constraint annotation="ELAssert">
                    <element name="expression">...</element>
                    <element name="validationAppliesTo">PARAMETERS</element>
                </constraint>
            </cross-parameter>
        </method>
        <method name="paintCar">
            <parameter type="int"/>
            <return-value>
                <constraint annotation="ELAssert">
                    <element name="expression">...</element>
                    <element name="validationAppliesTo">RETURN_VALUE</element>
                </constraint>
            </return-value>
        </method>
    </bean>

</constraint-mappings>

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 Section 5.3, “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 Section 5.4, “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.

<constraint-definition annotation="org.hibernate.validator.constraints.URL">
  <validated-by include-existing-validators="false">
    <value>org.hibernate.validator.constraintvalidators.RegexpURLValidator</value>
  </validated-by>
</constraint-definition>

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.

Example 8.1, “Bootstrapping default ValidatorFactory and Validator” shows how to obtain a validator from the default validator factory:

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

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 Example 8.2, “Bootstrapping ValidatorFactory and Validator using a specific provider”.

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

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 Example 8.3, “Retrieving the default ValidatorFactory for configuration”.

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

package org.hibernate.validator.referenceguide.chapter08;

public class OsgiServiceDiscoverer implements ValidationProviderResolver {

	@Override
	public List<ValidationProvider<?>> getValidationProviders() {
		//...
	}
}

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

By default validator factories retrieved from Validation and any validators they create are configured as per the XML descriptor META-INF/validation.xml (see Chapter 7, 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.

package org.hibernate.validator.referenceguide.chapter08;

public class MyMessageInterpolator implements MessageInterpolator {

	@Override
	public String interpolate(String messageTemplate, Context context) {
		//...
	}

	@Override
	public String interpolate(String messageTemplate, Context context, Locale locale) {
		//...
	}
}

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

package org.hibernate.validator.referenceguide.chapter08;

public class MyTraversableResolver implements TraversableResolver {

	@Override
	public boolean isReachable(
			Object traversableObject,
			Node traversableProperty,
			Class<?> rootBeanType,
			Path pathToTraversableObject,
			ElementType elementType) {
		//...
	}

	@Override
	public boolean isCascadable(
			Object traversableObject,
			Node traversableProperty,
			Class<?> rootBeanType,
			Path pathToTraversableObject,
			ElementType elementType) {
		//...
	}
}

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

package org.hibernate.validator.referenceguide.chapter08;

public class MyConstraintValidatorFactory implements ConstraintValidatorFactory {

	@Override
	public <T extends ConstraintValidator<?, ?>> T getInstance(Class<T> key) {
		//...
	}

	@Override
	public void releaseInstance(ConstraintValidator<?, ?> instance) {
		//...
	}
}

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

package org.hibernate.validator.referenceguide.chapter08;

public class MyParameterNameProvider implements ParameterNameProvider {

	@Override
	public List<String> getParameterNames(Constructor<?> constructor) {
		//...
	}

	@Override
	public List<String> getParameterNames(Method method) {
		//...
	}
}

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

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

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

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

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

ValidatorFactory validatorFactory = Validation.buildDefaultValidatorFactory();

Validator validator = validatorFactory.usingContext()
		.messageInterpolator( new MyMessageInterpolator() )
		.traversableResolver( new MyTraversableResolver() )
		.getValidator();

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.

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

Validator validator = Validation.buildDefaultValidatorFactory().getValidator();

BeanDescriptor carDescriptor = validator.getConstraintsForClass( Car.class );

assertTrue( carDescriptor.isBeanConstrained() );

//one class-level constraint
assertEquals( 1, carDescriptor.getConstraintDescriptors().size() );

//manufacturer, licensePlate, driver
assertEquals( 3, carDescriptor.getConstrainedProperties().size() );

//property has constraint
assertNotNull( carDescriptor.getConstraintsForProperty( "licensePlate" ) );

//property is marked with @Valid
assertNotNull( carDescriptor.getConstraintsForProperty( "driver" ) );

//constraints from getter method in interface and implementation class are returned
assertEquals(
		2,
		carDescriptor.getConstraintsForProperty( "manufacturer" )
				.getConstraintDescriptors()
				.size()
);

//property is not constrained
assertNull( carDescriptor.getConstraintsForProperty( "modelName" ) );

//driveAway(int), load(List<Person>, List<PieceOfLuggage>)
assertEquals( 2, carDescriptor.getConstrainedMethods( MethodType.NON_GETTER ).size() );

//driveAway(int), getManufacturer(), getDriver(), load(List<Person>, List<PieceOfLuggage>)
assertEquals(
		4,
		carDescriptor.getConstrainedMethods( MethodType.NON_GETTER, MethodType.GETTER )
				.size()
);

//driveAway(int)
assertNotNull( carDescriptor.getConstraintsForMethod( "driveAway", int.class ) );

//getManufacturer()
assertNotNull( carDescriptor.getConstraintsForMethod( "getManufacturer" ) );

//setManufacturer() is not constrained
assertNull( carDescriptor.getConstraintsForMethod( "setManufacturer", String.class ) );

//Car(String, String, Person, String)
assertEquals( 1, carDescriptor.getConstrainedConstructors().size() );

//Car(String, String, Person, String)
assertNotNull(
		carDescriptor.getConstraintsForConstructor(
				String.class,
				String.class,
				Person.class,
				String.class
		)
);

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 Section 9.4, “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 Section 9.6, “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 Section 2.1.5, “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. Example 9.3, “Using PropertyDescriptor” shows how to use the PropertyDescriptor interface.

PropertyDescriptor licensePlateDescriptor = carDescriptor.getConstraintsForProperty(
		"licensePlate"
);

//"licensePlate" has two constraints, is not marked with @Valid and defines no group conversions
assertEquals( "licensePlate", licensePlateDescriptor.getPropertyName() );
assertEquals( 2, licensePlateDescriptor.getConstraintDescriptors().size() );
assertTrue( licensePlateDescriptor.hasConstraints() );
assertFalse( licensePlateDescriptor.isCascaded() );
assertTrue( licensePlateDescriptor.getGroupConversions().isEmpty() );

PropertyDescriptor driverDescriptor = carDescriptor.getConstraintsForProperty( "driver" );

//"driver" has no constraints, is marked with @Valid and defines one group conversion
assertEquals( "driver", driverDescriptor.getPropertyName() );
assertTrue( driverDescriptor.getConstraintDescriptors().isEmpty() );
assertFalse( driverDescriptor.hasConstraints() );
assertTrue( driverDescriptor.isCascaded() );
assertEquals( 1, driverDescriptor.getGroupConversions().size() );

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 Section 9.5, “GroupConversionDescriptor” for more details on GroupConversionDescriptor.

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

//driveAway(int) has a constrained parameter and an unconstrained return value
MethodDescriptor driveAwayDescriptor = carDescriptor.getConstraintsForMethod(
		"driveAway",
		int.class
);
assertEquals( "driveAway", driveAwayDescriptor.getName() );
assertTrue( driveAwayDescriptor.hasConstrainedParameters() );
assertFalse( driveAwayDescriptor.hasConstrainedReturnValue() );

//always returns an empty set; constraints are retrievable by navigating to
//one of the sub-descriptors, e.g. for the return value
assertTrue( driveAwayDescriptor.getConstraintDescriptors().isEmpty() );

ParameterDescriptor speedDescriptor = driveAwayDescriptor.getParameterDescriptors()
		.get( 0 );

//The "speed" parameter is located at index 0, has one constraint and is not cascaded
//nor does it define group conversions
assertEquals( "arg0", speedDescriptor.getName() );
assertEquals( 0, speedDescriptor.getIndex() );
assertEquals( 1, speedDescriptor.getConstraintDescriptors().size() );
assertFalse( speedDescriptor.isCascaded() );
assert speedDescriptor.getGroupConversions().isEmpty();

//getDriver() has no constrained parameters but its return value is marked for cascaded
//validation and declares one group conversion
MethodDescriptor getDriverDescriptor = carDescriptor.getConstraintsForMethod(
		"getDriver"
);
assertFalse( getDriverDescriptor.hasConstrainedParameters() );
assertTrue( getDriverDescriptor.hasConstrainedReturnValue() );

ReturnValueDescriptor returnValueDescriptor = getDriverDescriptor.getReturnValueDescriptor();
assertTrue( returnValueDescriptor.getConstraintDescriptors().isEmpty() );
assertTrue( returnValueDescriptor.isCascaded() );
assertEquals( 1, returnValueDescriptor.getGroupConversions().size() );

//load(List<Person>, List<PieceOfLuggage>) has one cross-parameter constraint
MethodDescriptor loadDescriptor = carDescriptor.getConstraintsForMethod(
		"load",
		List.class,
		List.class
);
assertTrue( loadDescriptor.hasConstrainedParameters() );
assertFalse( loadDescriptor.hasConstrainedReturnValue() );
assertEquals(
		1,
		loadDescriptor.getCrossParameterDescriptor().getConstraintDescriptors().size()
);

//Car(String, String, Person, String) has one constrained parameter
ConstructorDescriptor constructorDescriptor = carDescriptor.getConstraintsForConstructor(
		String.class,
		String.class,
		Person.class,
		String.class
);

assertEquals( "Car", constructorDescriptor.getName() );
assertFalse( constructorDescriptor.hasConstrainedReturnValue() );
assertTrue( constructorDescriptor.hasConstrainedParameters() );
assertEquals(
		1,
		constructorDescriptor.getParameterDescriptors()
				.get( 0 )
				.getConstraintDescriptors()
				.size()
);

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 Section 8.2.4, “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

Example 9.5, “Using ElementDescriptor methods” shows how these methods are used.

PropertyDescriptor manufacturerDescriptor = carDescriptor.getConstraintsForProperty(
		"manufacturer"
);

assertTrue( manufacturerDescriptor.hasConstraints() );
assertEquals( String.class, manufacturerDescriptor.getElementClass() );

CrossParameterDescriptor loadCrossParameterDescriptor = carDescriptor.getConstraintsForMethod(
		"load",
		List.class,
		List.class
).getCrossParameterDescriptor();

assertTrue( loadCrossParameterDescriptor.hasConstraints() );
assertEquals( Object[].class, loadCrossParameterDescriptor.getElementClass() );

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

PropertyDescriptor manufacturerDescriptor = carDescriptor.getConstraintsForProperty(
		"manufacturer"
);

//"manufacturer" constraints are declared on the getter, not the field
assertTrue(
		manufacturerDescriptor.findConstraints()
				.declaredOn( ElementType.FIELD )
				.getConstraintDescriptors()
				.isEmpty()
);

//@NotNull on Vehicle#getManufacturer() is part of another group
assertEquals(
		1,
		manufacturerDescriptor.findConstraints()
				.unorderedAndMatchingGroups( Default.class )
				.getConstraintDescriptors()
				.size()
);

//@Size on Car#getManufacturer()
assertEquals(
		1,
		manufacturerDescriptor.findConstraints()
				.lookingAt( Scope.LOCAL_ELEMENT )
				.getConstraintDescriptors()
				.size()
);

//@Size on Car#getManufacturer() and @NotNull on Vehicle#getManufacturer()
assertEquals(
		2,
		manufacturerDescriptor.findConstraints()
				.lookingAt( Scope.HIERARCHY )
				.getConstraintDescriptors()
				.size()
);

//Combining several filter options
assertEquals(
		1,
		manufacturerDescriptor.findConstraints()
				.declaredOn( ElementType.METHOD )
				.lookingAt( Scope.HIERARCHY )
				.unorderedAndMatchingGroups( Vehicle.Basic.class )
				.getConstraintDescriptors()
				.size()
);

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. Example 9.7, “Using GroupConversionDescriptor” shows an example.

PropertyDescriptor driverDescriptor = carDescriptor.getConstraintsForProperty( "driver" );

Set<GroupConversionDescriptor> groupConversions = driverDescriptor.getGroupConversions();
assertEquals( 1, groupConversions.size() );

GroupConversionDescriptor groupConversionDescriptor = groupConversions.iterator()
		.next();
assertEquals( Default.class, groupConversionDescriptor.getFrom() );
assertEquals( Person.Basic.class, groupConversionDescriptor.getTo() );

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.

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

//descriptor for the @LuggageCountMatchesPassengerCount constraint on the
//load(List<Person>, List<PieceOfLuggage>) method
ConstraintDescriptor<?> constraintDescriptor = carDescriptor.getConstraintsForMethod(
		"load",
		List.class,
		List.class
).getCrossParameterDescriptor().getConstraintDescriptors().iterator().next();

//constraint type
assertEquals(
		LuggageCountMatchesPassengerCount.class,
		constraintDescriptor.getAnnotation().annotationType()
);

//standard constraint attributes
assertEquals( SeverityInfo.class, constraintDescriptor.getPayload().iterator().next() );
assertEquals(
		ConstraintTarget.PARAMETERS,
		constraintDescriptor.getValidationAppliesTo()
);
assertEquals( Default.class, constraintDescriptor.getGroups().iterator().next() );
assertEquals(
		"There must not be more than {piecesOfLuggagePerPassenger} pieces of luggage per " +
		"passenger.",
		constraintDescriptor.getMessageTemplate()
);

//custom constraint attribute
assertEquals(
		2,
		constraintDescriptor.getAttributes().get( "piecesOfLuggagePerPassenger" )
);

//no composing constraints
assertTrue( constraintDescriptor.getComposingConstraints().isEmpty() );

//validator class
assertEquals(
		Arrays.<Class<?>>asList( LuggageCountMatchesPassengerCount.Validator.class ),
		constraintDescriptor.getConstraintValidatorClasses()
);

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

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

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

<h:form>

  <f:validateBean validationGroups="javax.validation.groups.Default">

    <h:inputText value=#{model.property}/>
    <h:selectOneRadio value=#{model.radioProperty}> ... </h:selectOneRadio>
    <!-- other input components here -->

  </f:validateBean>

</h:form>

javax.faces.validator.BeanValidator.MESSAGE={1}: {0}

javax.faces.validator.BeanValidator.MESSAGE={0}

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 Jave 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 Section 1.1.2, “CDI”.

package org.hibernate.validator.referenceguide.chapter10.cdi.validator;

@ApplicationScoped
public class RentalStation {

	@Inject
	private ValidatorFactory validatorFactory;

	@Inject
	private Validator validator;

	//...
}

package org.hibernate.validator.referenceguide.chapter10.cdi.validator.qualifier;

@ApplicationScoped
public class RentalStation {

	@Inject
	@HibernateValidator
	private ValidatorFactory validatorFactory;

	@Inject
	@HibernateValidator
	private Validator validator;

	//...
}

package org.hibernate.validator.referenceguide.chapter10.cdi.injection;

public class ValidLicensePlateValidator
		implements ConstraintValidator<ValidLicensePlate, String> {

	@Inject
	private VehicleRegistry vehicleRegistry;

	@PostConstruct
	public void postConstruct() {
		//do initialization logic...
	}

	@PreDestroy
	public void preDestroy() {
		//do destruction logic...
	}

	@Override
	public void initialize(ValidLicensePlate constraintAnnotation) {
	}

	@Override
	public boolean isValid(String licensePlate, ConstraintValidatorContext constraintContext) {
		return vehicleRegistry.isValidLicensePlate( licensePlate );
	}
}

package org.hibernate.validator.referenceguide.chapter10.cdi.methodvalidation;

@ApplicationScoped
public class RentalStation {

	@Valid
	public RentalStation() {
		//...
	}

	@NotNull
	@Valid
	public Car rentCar(
			@NotNull Customer customer,
			@NotNull @Future Date startDate,
			@Min(1) int durationInDays) {
		//...
	}

	@NotNull
	List<Car> getAvailableCars() {
		//...
	}
}

package org.hibernate.validator.referenceguide.chapter10.cdi.methodvalidation;

@RequestScoped
public class RentCarRequest {

	@Inject
	private RentalStation rentalStation;

	public void rentCar(String customerId, Date startDate, int duration) {
		//causes ConstraintViolationException
		rentalStation.rentCar( null, null, -1 );
	}
}

package org.hibernate.validator.referenceguide.chapter10.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) {
		//...
	}

	@NotNull
	public List<Car> getAvailableCars() {
		//...
	}
}

package org.hibernate.validator.referenceguide.chapter10.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);
}

package org.hibernate.validator.referenceguide.chapter10.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) {
		//...
	}
}

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 Example 10.9, “Retrieving Validator and ValidatorFactory via @Resource injection”.

package org.hibernate.validator.referenceguide.chapter10.javaee;

@Stateless
public class RentalStationBean {

	@Resource
	private ValidatorFactory validatorFactory;

	@Resource
	private Validator validator;

	//...
}

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 Chapter 7, 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 Section 11.13.2, “JavaFX unwrapper” for examples and further discussion.

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

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.3.6.Final the Hibernate Validator Annotation Processor checks that:

The behavior of the Hibernate Validator Annotation Processor can be controlled using the processor options listed in table Table 12.1, “Hibernate Validator Annotation 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).

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

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

...
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-validator-annotation-processor</artifactId>
    <version>5.3.6.Final</version>
</dependency>
...

...
<plugin>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <source>1.6</source>
        <target>1.6</target>
        <compilerArgument>-proc:none</compilerArgument>
    </configuration>
</plugin>
<plugin>
    <groupId>org.bsc.maven</groupId>
    <artifactId>maven-processor-plugin</artifactId>
    <version>2.2.1</version>
    <executions>
        <execution>
            <id>process</id>
            <goals>
                <goal>process</goal>
            </goals>
            <phase>process-sources</phase>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate-validator-annotation-processor</artifactId>
            <version>5.3.6.Final</version>
        </dependency>
    </dependencies>
</plugin>
...

12.4.2. IDE builds

12.4.2.1. Eclipse

Do the following to use the annotation processor within the Eclipse IDE:

• Right-click your project, choose "Properties"
• Go to "Java Compiler" and make sure, that "Compiler compliance level" is set to "1.6". Otherwise the processor won’t be activated
• Go to "Java Compiler - Annotation Processing" and choose "Enable annotation processing"
• Go to "Java Compiler - Annotation Processing - Factory Path" and add the JAR hibernate-validator-annotation-processor-5.3.6.Final.jar
• Confirm the workspace rebuild

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

12.4.2.2. IntelliJ IDEA

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

• Go to "File", then "Settings",
• Expand the node "Compiler", then "Annotation Processors"
• Choose "Enable annotation processing" and enter the following as "Processor path": /path/to/hibernate-validator-annotation-processor-5.3.6.Final.jar
• Add the processor’s fully qualified name org.hibernate.validator.ap.ConstraintValidationProcessor to the "Annotation Processors" list
• If applicable add you module to the "Processed Modules" list

Rebuilding your project then should show any erronous constraint annotations:

12.4.2.3. NetBeans

Starting with version 6.9, also the NetBeans IDE supports using annotation processors within the IDE build. To do so, do the following:

• Right-click your project, choose "Properties"
• Go to "Libraries", tab "Processor", and add the JAR hibernate-validator-annotation-processor-5.3.6.Final.jar
• Go to "Build - Compiling", select "Enable Annotation Processing" and "Enable Annotation Processing in Editor". Add the annotation processor by specifying its fully qualified name org.hibernate.validator.ap.ConstraintValidationProcessor

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

The following known issues exist as of May 2010: