Hibernate.orgCommunity Documentation

Hibernate Validator

JSR 303 Reference Implementation

Reference Guide


Preface
1. Getting started
1.1. Project set up
1.2. Applying constraints
1.3. Validating constraints
1.4. Where to go next?
2. Validation step by step
2.1. Defining constraints
2.1.1. Field-level constraints
2.1.2. Property-level constraints
2.1.3. Class-level constraints
2.1.4. Constraint inheritance
2.1.5. Object graphs
2.2. Validating constraints
2.2.1. Obtaining a Validator instance
2.2.2. Validator methods
2.2.3. ConstraintViolation methods
2.2.4. Message interpolation
2.3. Validating groups
2.3.1. Group sequences
2.3.2. Redefining the default group sequence of a class
2.4. Built-in constraints
2.4.1. Bean Validation constraints
2.4.2. Additional constraints
3. Creating custom constraints
3.1. Creating a simple constraint
3.1.1. The constraint annotation
3.1.2. The constraint validator
3.1.3. The error message
3.1.4. Using the constraint
3.2. Constraint composition
4. XML configuration
4.1. validation.xml
4.2. Mapping constraints
5. Bootstrapping
5.1. Configuration and ValidatorFactory
5.2. ValidationProviderResolver
5.3. MessageInterpolator
5.3.1. ResourceBundleLocator
5.4. TraversableResolver
5.5. ConstraintValidatorFactory
6. Metadata API
6.1. BeanDescriptor
6.2. PropertyDescriptor
6.3. ElementDescriptor
6.4. ConstraintDescriptor
7. Integration with other frameworks
7.1. OSGi
7.2. Database schema-level validation
7.3. ORM integration
7.3.1. Hibernate event-based validation
7.3.2. JPA
7.4. Presentation layer validation
8. Hibernate Validator Specifics
8.1. Public API
8.2. Fail fast mode
8.3. Method validation
8.3.1. Defining method-level constraints
8.3.2. Evaluating method-level constraints
8.3.3. Retrieving method-level constraint meta data
8.4. Programmatic constraint definition
8.5. Boolean composition for constraint composition
9. Annotation Processor
9.1. Prerequisites
9.2. Features
9.3. Options
9.4. Using the Annotation Processor
9.4.1. Command line builds
9.4.2. IDE builds
9.5. Known issues
10. Further reading

This chapter will show you how to get started with Hibernate Validator, the reference implementation (RI) of Bean Validation. For the following quickstart you need:

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


Alternatively, you can start by creating a sample project using Hibernate Validator's Quickstart Maven archetype as follows:


Maven will create your project in the directory hv-quickstart. Change into this directory and run:

mvn test

Maven will compile the example code and run the implemented unit tests. Let's have a look at the actual code in the next section.

To perform a validation of these constraints, we use a Validator instance. Let's have a look at the CarTest class:

Example 1.5. Class CarTest showing validation examples

package com.mycompany;


import static org.junit.Assert.*;
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;
public class CarTest {
    private static Validator validator;
    @BeforeClass
    public static void setUp() {
        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 we get a Validator instance from the ValidatorFactory. A Validator instance is thread-safe and may be reused multiple times. For this reason we store it as field of our test class. We can use the Validator now to validate the different car instances in the test methods.

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

  • The @NotNull constraint on manufacturer is violated in manufacturerIsNull()

  • The @Size constraint on licensePlate is violated in licensePlateTooShort()

  • The @Min constraint on seatCount is violated in seatCountTooLow()

If the object validates successfully, validate() returns an empty set.

Note that we only use classes from the package javax.validation from the Bean Validation API. As we don't reference any classes of the RI directly, it would be no problem to switch to another implementation of the API, should that need arise.

In this chapter we will see in more detail how to use Hibernate Validator to validate constraints for a given entity model. We will also learn which default constraints the Bean Validation specification provides and which additional constraints are only provided by Hibernate Validator. Let's start with how to add constraints to an entity.

Constraints in Bean Validation are expressed via Java annotations. In this section we show how to annotate an object model with these annotations. We have to differentiate between three different type of constraint annotations - field-, property-, and class-level annotations.

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

Note

The property's getter method has to be annotated, not its setter.


When using property level constraints property access strategy is used to access the value to be validated. This means the bean validation provider accesses the state via the property accessor method. One advantage of annotating properties instead of fields is that the constraints become part of the constrained type's API that way and users are aware of the existing constraints without having to examine the type's implementation.

Tip

It is recommended to stick either to field or property annotations within one class. It is not recommended to annotate a field and the accompanying getter method as this would cause the field to be validated twice.

Last but not least, a constraint can also be placed on class level. When a constraint annotation is placed on this level the class instance itself passed to the ConstraintValidator. Class level constraints are useful if it is necessary to inspect more than a single property of the class to validate it or if a correlation between different state variables has to be evaluated. In Example 2.3, “Class level constraint” we add the property passengers to the class Car. We also add the constraint PassengerCount on the class level. We will later see how we can actually create this custom constraint (see Chapter 3, Creating custom constraints). For now it is enough to know that PassengerCount will ensure that there cannot be more passengers in a car than there are seats.


When validating an object that implements an interface or extends another class, all constraint annotations on the implemented interface and parent class apply in the same manner as the constraints specified on the validated object itself. To make things clearer let's have a look at the following example:


Our well-known class Car is now extended by RentalCar with the additional property rentalStation. If an instance of RentalCar is validated, not only the @NotNull constraint on rentalStation is validated, but also the constraint on manufacturer from the parent class.

The same would hold true, if Car were an interface implemented by RentalCar.

Constraint annotations are aggregated if methods are overridden. If RentalCar would override the getManufacturer() method from Car any constraints annotated at the overriding method would be evaluated in addition to the @NotNull constraint from the super-class.

The Bean Validation API does not only allow to validate single class instances but also complete object graphs. To do so, just annotate a field or property representing a reference to another object with @Valid. If the parent object is validated, all referenced objects annotated with @Valid will be validated as well (as will be their children etc.). See Example 2.6, “Adding a driver to the car”.



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

Object graph validation also works for collection-typed fields. That means any attributes that

  • are arrays

  • implement java.lang.Iterable (especially Collection, List and Set)

  • implement java.util.Map

can be annotated with @Valid, which will cause each contained element to be validated, when the parent object is validated.


If a Car instance is validated, a ConstraintValidation will be created, if any of the Person objects contained in the passengers list has a null name.

Note

null values are getting ignored when validating object graphs.

The Validator interface is the main entry point to Bean Validation. In Section 5.1, “Configuration and ValidatorFactory” we will first show how to obtain an Validator instance. Afterwards we will learn how to use the different methods of the Validator interface.

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

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

All the validation methods have a var-args parameter which can be used to specify, which validation groups shall be considered when performing the validation. If the parameter is not specified the default validation group (javax.validation.groups.Default) will be used. We will go into more detail on the topic of validation groups in Section 2.3, “Validating groups”

As we will see in Chapter 3, Creating custom constraints each constraint definition must define a default message descriptor. This message can be overridden at declaration time using the message attribute of the constraint. You can see this in Example 2.13, “Driver”. This message descriptors get interpolated when a constraint validation fails using the configured MessageInterpolator. The interpolator will try to resolve any message parameters, meaning string literals enclosed in braces. In order to resolve these parameters Hibernate Validator's default MessageInterpolator first recursively resolves parameters against a custom ResourceBundle called ValidationMessages.properties at the root of the classpath (It is up to you to create this file). If no further replacements are possible against the custom bundle the default ResourceBundle under /org/hibernate/validator/ValidationMessages.properties gets evaluated. If a replacement occurs against the default bundle the algorithm looks again at the custom bundle (and so on). Once no further replacements against these two resource bundles are possible remaining parameters are getting resolved against the attributes of the constraint to be validated.

Since the braces { and } have special meaning in the messages they need to be escaped if they are used literally. The following The following rules apply:

  • \{ is considered as the literal {

  • \} is considered as the literal }

  • \\ is considered as the literal \

If the default message interpolator does not fit your requirements it is possible to plug a custom MessageInterpolator when the ValidatorFactory gets created. This can be seen in Chapter 5, Bootstrapping.

Groups allow you to restrict the set of constraints applied during validation. This makes for example wizard like validation possible where in each step only a specified subset of constraints get validated. The groups targeted are passed as var-args parameters to validate, validateProperty and validateValue. Let's have a look at an extended Car with Driver example. First we have the class Person (Example 2.12, “Person”) which has a @NotNull constraint on name. Since no group is specified for this annotation its default group is javax.validation.groups.Default.

Note

When more than one group is requested, the order in which the groups are evaluated is not deterministic. If no group is specified the default group javax.validation.groups.Default is assumed.


Next we have the class Driver (Example 2.13, “Driver”) extending Person. Here we are adding the properties age and hasDrivingLicense. In order to drive you must be at least 18 (@Min(18)) and you must have a driving license (@AssertTrue). Both constraints defined on these properties belong to the group DriverChecks. As you can see in Example 2.14, “Group interfaces” the group DriverChecks is just a simple tagging interface. Using interfaces makes the usage of groups type safe and allows for easy refactoring. It also means that groups can inherit from each other via class inheritance.



Last but not least we add the property passedVehicleInspection to the Car class (Example 2.15, “Car”) indicating whether a car passed the road worthy tests.


Overall three different groups are used in our example. Person.name, Car.manufacturer, Car.licensePlate and Car.seatCount all belong to the Default group. Driver.age and Driver.hasDrivingLicense belong to DriverChecks and last but not least Car.passedVehicleInspection belongs to the group CarChecks. Example 2.16, “Drive away” shows how passing different group combinations to the Validator.validate method result in different validation results.

Example 2.16. Drive away

public class GroupTest {


    private static Validator validator;
    @BeforeClass
    public static void setUp() {
        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        validator = factory.getValidator();
    }
    @Test
    public void driveAway() {
        // 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 ).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() );
    }
}

First we create a car and validate it 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. Next we just validate the CarChecks group which will fail until we make sure that the car passes the vehicle inspection. When we then add a driver to the car and validate against DriverChecks we get again a 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 will pass.

Last but not least, we show 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 our example from Section 2.3, “Validating groups” we could for example require that first all default car constraints are passing before we check the road worthiness of the car. Finally before we drive away we check the actual driver constraints. In order to implement such an order one would define a new interface and annotate it with @GroupSequence defining the order in which the groups have to be validated.

Note

If at least one constraint fails in a sequenced group none of the constraints of the following groups in the sequence get validated.


Warning

Groups defining a sequence and groups composing a sequence must not be involved in a cyclic dependency either directly or indirectly, either through cascaded sequence definition or group inheritance. If a group containing such a circularity is evaluated, a GroupDefinitionException is raised.

The usage of the new sequence could then look like in Example 2.18, “Usage of a group sequence”.


The @GroupSequence annotation also fulfills a second purpose. It allows you to redefine what the Default group means for a given class. To redefine Default for a given class, add a @GroupSequence annotation to the class. The defined groups in the annotation express the sequence of groups that substitute Default for this class. Example 2.19, “RentalCar with @GroupSequence” introduces a new class RentalCar with a redefined default group. With this definition you can evaluate the constraints belonging to RentalChecks, CarChecks and RentalCar by just requesting the Default group as seen in Example 2.20, “RentalCar with redefined default group”.



Note

Due to the fact that there cannot be a cyclic dependency in the group and group sequence definitions one cannot just add Default to the sequence redefining Default for a class. Instead the class itself has to be added!

Note

The Default group sequence overriding is local to the class it is defined on and is not propagated to the associated objects. This means in particular that adding DriverChecks to the default group sequence of RentalCar would not have any effects. Only the group Default will be propagated to the driver association when validation a rental car instance.

The @javax.validation.GroupSequence annotation is a standardized Bean Validation annotation. As seen in the previous section it allows you to statically redefine the default group sequence for a class. Hibernate Validator also offers a custom, non standardized annotation - org.hibernate.validator.group.GroupSequenceProvider - which allows for dynamic redefinition of the default group sequence. Using the rental car scenario again, one could dynamically add the CarChecks as seen in Example 2.21, “RentalCar with @GroupSequenceProvider” and Example , “DefaultGroupSequenceProvider implementation”.



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

Table 2.2, “Bean Validation constraints” shows purpose and supported data types of all constraints specified in the Bean Validation API. All these constraints apply to the field/property level, there are no class-level constraints defined in the Bean Validation specification. If you are using the Hibernate object-relational mapper, some of the constraints are taken into account when creating the DDL for your model (see column "Hibernate metadata impact").

Note

Hibernate Validator allows some constraints to be applied to more data types than required by the Bean Validation specification (e.g. @Max can be applied to Strings). Relying on this feature can impact portability of your application between Bean Validation providers.

Table 2.2. Bean Validation constraints

AnnotationSupported data typesUseHibernate metadata impact
@AssertFalseBoolean, booleanChecks that the annotated element is false.none
@AssertTrueBoolean, booleanChecks that the annotated element is true.none
@DecimalMaxBigDecimal, BigInteger, String, byte, short, int, long and the respective wrappers of the primitive types. Additionally supported by HV: any sub-type of Number and CharSequence.The annotated element must be a number whose value must be lower or equal to the specified maximum. The parameter value is the string representation of the max value according to the BigDecimal string representation.none
@DecimalMinBigDecimal, BigInteger, String, byte, short, int, long and the respective wrappers of the primitive types. Additionally supported by HV: any sub-type of Number and CharSequence.The annotated element must be a number whose value must be higher or equal to the specified minimum. The parameter value is the string representation of the min value according to the BigDecimal string representation.none
@Digits(integer=, fraction=)BigDecimal, BigInteger, String, byte, short, int, long and the respective wrappers of the primitive types. Additionally supported by HV: any sub-type of Number and CharSequence.Checks whether the annoted value is a number having up to integer digits and fraction fractional digits.Define column precision and scale.
@Futurejava.util.Date, java.util.Calendar; Additionally supported by HV, if the Joda Time date/time API is on the class path: any implementations of ReadablePartial and ReadableInstant.Checks whether the annotated date is in the future.none
@MaxBigDecimal, BigInteger, byte, short, int, long and the respective wrappers of the primitive types. Additionally supported by HV: any sub-type ofCharSequence (the numeric value represented by the character sequence is evaluated), any sub-type of Number.Checks whether the annotated value is less than or equal to the specified maximum.Add a check constraint on the column.
@MinBigDecimal, BigInteger, byte, short, int, long and the respective wrappers of the primitive types. Additionally supported by HV: any sub-type of CharSequence (the numeric value represented by the char sequence is evaluated), any sub-type of Number.Checks whether the annotated value is higher than or equal to the specified minimum.Add a check constraint on the column.
@NotNullAny typeChecks that the annotated value is not null.Column(s) are not null.
@NullAny typeChecks that the annotated value is null.none
@Pastjava.util.Date, java.util.Calendar; Additionally supported by HV, if the Joda Time date/time API is on the class path: any implementations of ReadablePartial and ReadableInstant.Checks whether the annotated date is in the past.none
@Pattern(regex=, flag=)String. Additionally supported by HV: any sub-type of CharSequence.Checks if the annotated string matches the regular expression regex considering the given flag match.none
@Size(min=, max=)String, Collection, Map and arrays. Additionally supported by HV: any sub-type of CharSequence.Checks if the annotated element's size is between min and max (inclusive).Column length will be set to max.
@ValidAny non-primitive typePerforms validation recursively on the associated object. If the object is a collection or an array, the elements are validated recursively. If the object is a map, the value elements are validated recursively.none

Note

On top of the parameters indicated in Table 2.2, “Bean Validation constraints” each constraint supports the parameters message, groups and payload. This is a requirement of the Bean Validation specification.

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

Table 2.3. Custom constraints

AnnotationSupported data typesUseHibernate metadata impact
@CreditCardNumberCharSequenceChecks that the annotated character sequence passes the Luhn checksum test. Note, this validation aims to check for user mistakes, not credit card validity! See also Anatomy of Credit Card Numbers.none
@EmailCharSequenceChecks whether the specified character sequence is a valid email address. The optional parameters regexp and flags allow to specify an additional regular expression (including regular expression flags) which the email must match.none
@Length(min=, max=)CharSequenceValidates that the annotated character sequence is between min and max included.Column length will be set to max.
@ModCheck(modType=, multiplier=, startIndex=, endIndex=, checkDigitPosition=, ignoreNonDigitCharacters=)CharSequenceChecks that the digits within the annotated character sequence pass the mod 10 or mod 11 checksum algorithm. modType is used to select the modulo type and the multiplier determines the algorithm specific multiplier (see also Luhn algorithm). startIndex and endIndex allow to only run the modulo algorithm on the specified sub-string. checkDigitPosition allows to use an arbitrary digit within the character sequence to be the check digit. If not specified it is assumed that the check digit is part of the specified range. Last but not least, ignoreNonDigitCharacters allows to ignore non digit characters.none
@NotBlankCharSequenceChecks that the annotated character sequence is not null and the trimmed length is greater than 0. The difference to @NotEmpty is that this constraint can only be applied on strings and that trailing whitespaces are ignored.none
@NotEmptyCharSequence, Collection, Map and arraysChecks whether the annotated element is not null nor empty.none
@Range(min=, max=)BigDecimal, BigInteger, CharSequence, byte, short, int, long and the respective wrappers of the primitive typesChecks whether the annotated value lies between (inclusive) the specified minimum and maximum.none
@SafeHtml(whitelistType=, additionalTags=)CharSequenceChecks whether the annotated value contains potentially malicious fragments such as <script/>. In order to use this constraint, the jsoup library must be part of the class path. With the whitelistType attribute predefined whitelist types can be chosen. You can also specify additional html tags for the whitelist with the additionalTags attribute.none
@ScriptAssert(lang=, script=, alias=)Any typeChecks whether the given script can successfully be evaluated against the annotated element. In order to use this constraint, an implementation of the Java Scripting API as defined by JSR 223 ("Scripting for the JavaTM Platform") must part of the class path. The expressions to be evaluated can be written in any scripting or expression language, for which a JSR 223 compatible engine can be found in the class path.none
@URL(protocol=, host=, port=, regexp=, flags=)CharSequenceChecks if the annotated character sequence is a valid URL according to RFC2396. If any of the optional parameters protocol, host or port are specified, the corresponding URL fragments must match the specified values. The optional parameters regexp and flags allow to specify an additional regular expression (including regular expression flags) which the URL must match.none

Though the Bean Validation API defines a whole set of standard constraint annotations one can easily think of situations in which these standard annotations won't suffice. For these cases you are able to create custom constraints tailored to your specific validation requirements in a simple manner.

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

Let's write a constraint annotation, that can be used to express that a given string shall either be upper case or lower case. We'll apply it later on to the licensePlate field of the Car class from Chapter 1, Getting started to ensure, that the field is always an upper-case string.

First we need a way to express the two case modes. We might use String constants, but a better way to go is to use a Java 5 enum for that purpose:


Now we can define the actual constraint annotation. If you've never designed an annotation before, this may look a bit scary, but actually it's not that hard:


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

Besides those three mandatory attributes (message, groups and payload) we add another one allowing for the required case mode to be specified. The name value is a special one, which can be omitted upon using the annotation, if it is the only attribute specified, as e.g. in @CheckCase(CaseMode.UPPER).

In addition we annotate the annotation type with a couple of so-called meta annotations:

  • @Target({ METHOD, FIELD, ANNOTATION_TYPE }): Says, that methods, fields and annotation declarations may be annotated with @CheckCase (but not type declarations e.g.)

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

  • @Constraint(validatedBy = CheckCaseValidator.class): Specifies the validator to be used to validate elements annotated with @CheckCase

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

Tip

Hibernate Validator provides support for the validation of method parameters using constraint annotations (see Section 8.3, “Method validation”).

In order to use a custom constraint for parameter validation the ElementType.PARAMETER must be specified within the @Target annotation. This is already the case for all constraints defined by the Bean Validation API and also the custom constraints provided by Hibernate Validator.

Next, we need to implement a constraint validator, that's able to validate elements with a @CheckCase annotation. To do so, we implement the interface ConstraintValidator as shown below:


The ConstraintValidator interface defines two type parameters, which we set in our implementation. The first one specifies the annotation type to be validated (in our example CheckCase), the second one the type of elements, which the validator can handle (here String).

In case a constraint annotation is allowed at elements of different types, a ConstraintValidator for each allowed type has to be implemented and registered at the constraint annotation as shown above.

The implementation of the validator is straightforward. The initialize() method gives us access to the attribute values of the annotation to be validated. In the example we store the CaseMode in a field of the validator for further usage.

In the isValid() method we implement the logic, that determines, whether a String is valid according to a given @CheckCase annotation or not. This decision depends on the case mode retrieved in initialize(). As the Bean Validation specification recommends, we consider null values as being valid. If null is not a valid value for an element, it should be annotated with @NotNull explicitly.

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


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

Tip

It is important to end each new constraint violation with addConstraintViolation. Only after that the new constraint violation will be created.

In case you are implementing a ConstraintValidator a class level constraint it is also possible to adjust set the property path for the created constraint violations. This is important for the case where you validate multiple properties of the class or even traverse the object graph. A custom property path creation could look like Example 3.5, “Adding new ConstraintViolation with custom property path”.


Now that our first custom constraint is completed, we can use it in the Car class from the Chapter 1, Getting started chapter to specify that the licensePlate field shall only contain upper-case strings:


Finally let's demonstrate in a little test that the @CheckCase constraint is properly validated:


Looking at the licensePlate field of the Car class in Example 3.7, “Applying the CheckCase constraint”, we 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 we had a licensePlate field in another class, we would have to copy all constraint declarations to the other class as well, violating the DRY principle.

This problem can be tackled using compound constraints. In the following we create a new constraint annotation @ValidLicensePlate, that comprises the constraints @NotNull, @Size and @CheckCase:


To do so, we just have to annotate the constraint declaration with its comprising constraints (btw. that's exactly why we allowed annotation types as target for the @CheckCase annotation). As no additional validation is required for the @ValidLicensePlate annotation itself, we don't declare a validator within the @Constraint meta annotation.

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


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


The key to enable XML configuration for Hibernate Validator is the file validation.xml. If this file exists in the classpath its configuration will be applied when the ValidationFactory gets created. Example 4.1, “validation-configuration-1.0.xsd” shows a model view of the xsd valiation.xml has to adhere to.


Example 4.2, “validation.xml” shows the several configuration options of validation.xml.


Warning

There can only be one validation.xml in the classpath. If more than one is found an exception is thrown.

All settings shown in the validation.xml are optional and in the case of Example 4.2, “validation.xml” show the defaults used within Hibernate Validator. The node default-provider allows to choose the Bean Validation provider. This is useful if there is more than one provider in the classpath. message-interpolator, traversable-resolver and constraint-validator-factory allow to customize the javax.validation.MessageInterpolator, javax.validation.TraversableResolver resp. javax.validation.ConstraintValidatorFactory. The same configuration options are also available programmatically through the javax.validation.Configuration. In fact XML configuration will be overridden by values explicitly specified via the API. It is even possible to ignore the XML configuration completely via Configuration.ignoreXmlConfiguration(). See also Chapter 5, Bootstrapping.

Via the constraint-mapping you can list an arbitrary number of additional XML files containing the actual constraint configuration. See Section 4.2, “Mapping constraints”.

Last but not least, you can specify provider specific properties via the property nodes.

Expressing constraints in XML is possible via files adhering to the xsd seen in Example 4.3, “validation-mapping-1.0.xsd”. Note that these mapping files are only processed if listed via constraint-mapping in your validation.xml.


Example 4.4, “constraints-car.xml” shows how our classes Car and RentalCar from Example 2.15, “Car” resp. Example 2.19, “RentalCar with @GroupSequence” could be mapped in XML.

Example 4.4. constraints-car.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.0.xsd"
                     xmlns="http://jboss.org/xml/ns/javax/validation/mapping">
    <default-package>org.hibernate.validator.quickstart</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>

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

Warning

A given entity can only be configured once across all configuration files. If the same class is configured more than once an exception is thrown.

Settings 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 and getter. If not explicitly specified on these levels the configured bean value applies. Otherwise do the nodes class, fields and getter determine on which level the constraints are placed (see Section 2.1, “Defining constraints”). 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 the element node.

The class node also allows to reconfigure the default group sequence (see Section 2.3.2, “Redefining the default group sequence of a class”) via the group-sequence node.

Last but not least, the list of ConstraintValidators 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 elements 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 ConstraintValidators described in XML are concatenated to the list of validators described on the annotation.

We already seen in Section 5.1, “Configuration and ValidatorFactory” the easiest way to create a Validator instance - Validation.buildDefaultValidatorFactory. In this chapter we have a look at the other methods in javax.validation.Validation and how they allow to configure several aspects of Bean Validation at bootstrapping time.

The different bootstrapping options allow, amongst other things, to bootstrap any Bean Validation implementation on the classpath. Generally, an available provider is discovered by the Java Service Provider mechanism. A Bean Validation implementation includes the file javax.validation.spi.ValidationProvider in META-INF/services. This file contains the fully qualified classname of the ValidationProvider of the implementation. In the case of Hibernate Validator this is org.hibernate.validator.HibernateValidator.

Note

If there are more than one Bean Validation implementation providers in the classpath and Validation.buildDefaultValidatorFactory() is used, there is no guarantee which provider will be chosen. To enforce the provider Validation.byProvider() should be used.

There are three different methods in the Validation class to create a Validator instance. The easiest in shown in Example 5.1, “Validation.buildDefaultValidatorFactory()”.


You can also use the method Validation.byDefaultProvider() which will allow you to configure several aspects of the created Validator instance:


We will learn more about MessageInterpolator, TraversableResolver and ConstraintValidatorFactory in the following sections.

Last but not least you can ask for a Configuration object of a specific Bean Validation provider. This is useful if you have more than one Bean Validation provider in your classpath. In this situation you can make an explicit choice about which implementation to use. In the case of Hibernate Validator the Validator creation looks like:


Tip

The generated Validator instance is thread safe and can be cached.

Section 2.2.4, “Message interpolation” already discussed the default message interpolation algorithm. If you have special requirements for your message interpolation you can provide a custom interpolator using Configuration.messageInterpolator(). This message interpolator will be shared by all validators generated by the ValidatorFactory created from this Configuration. Example 5.6, “Providing a custom MessageInterpolator” shows an interpolator (available in Hibernate Validator) which can interpolate the value being validated in the constraint message. To refer to this value in the constraint message you can use:

  • ${validatedValue}: this will call String.valueOf on the validated value.

  • ${validatedValue:<format>}: provide your own format string which will be passed to String.format together with the validated value. Refer to the javadoc of String.format for more information about the format options.


Tip

It is recommended that MessageInterpolator implementations delegate final interpolation to the Bean Validation default MessageInterpolator to ensure standard Bean Validation interpolation rules are followed. The default implementation is accessible through Configuration.getDefaultMessageInterpolator().

A common use case is the ability to specify your own resource bundles for message interpolation. The default MessageInterpolator implementation in Hibernate Validator is called ResourceBundleMessageInterpolator and per default loads resource bundles via ResourceBundle.getBundle. However, ResourceBundleMessageInterpolator also allows you to specify a custom implementation of ResourceBundleLocator allowing you to provide your own resource bundles. Example 5.7, “Providing a custom ResourceBundleLocator” shows an example. In the example HibernateValidatorConfiguration.getDefaultResourceBundleLocator is used to retrieve the default ResourceBundleLocator which then can be passed to the custom implementation in order implement delegation.


Hibernate Validator provides the following implementation of ResourceBundleLocator - PlatformResourceBundleLocator (the default) and AggregateResourceBundleLocator. The latter can be used to specify a list of resource bundle names which will get loaded and merged into a single resource bundle. Refer to the JavaDoc documentation for more information.

The usage of the TraversableResolver has so far not been discussed. The idea is that in some cases, the state of a property should not be accessed. The most obvious example for that is a lazy loaded property or association of a Java Persistence provider. Validating this lazy property or association would mean that its state would have to be accessed triggering a load from the database. Bean Validation controls which property can and cannot be accessed via the TraversableResolver interface (see Example 5.8, “TraversableResolver interface”). In the example HibernateValidatorConfiguration.

Example 5.8. TraversableResolver interface

/**

 * Contract determining if a property can be accessed by the Bean Validation provider
 * This contract is called for each property that is being either validated or cascaded.
 *
 * A traversable resolver implementation must be thread-safe.
 *
 */
public interface TraversableResolver {
    /**
     * Determine if the Bean Validation provider is allowed to reach the property state
     *
     * @param traversableObject object hosting <code>traversableProperty</code> or null  
     *                          if validateValue is called
     * @param traversableProperty the traversable property.
     * @param rootBeanType type of the root object passed to the Validator.
     * @param pathToTraversableObject path from the root object to
     *        <code>traversableObject</code>
     *        (using the path specification defined by Bean Validator).
     * @param elementType either <code>FIELD</code> or <code>METHOD</code>.
     *
     * @return <code>true</code> if the Bean Validation provider is allowed to
     *         reach the property state, <code>false</code> otherwise.
     */
     boolean isReachable(Object traversableObject,
                         Path.Node traversableProperty,
                         Class<?> rootBeanType,
                         Path pathToTraversableObject,
                         ElementType elementType);
    /**
     * Determine if the Bean Validation provider is allowed to cascade validation on
     * the bean instance returned by the property value
     * marked as <code>@Valid</code>.
     * Note that this method is called only if isReachable returns true for the same set of
     * arguments and if the property is marked as <code>@Valid</code>
     *
     * @param traversableObject object hosting <code>traversableProperty</code> or null
     *                          if validateValue is called
     * @param traversableProperty the traversable property.
     * @param rootBeanType type of the root object passed to the Validator.
     * @param pathToTraversableObject path from the root object to
     *        <code>traversableObject</code>
     *        (using the path specification defined by Bean Validator).
     * @param elementType either <code>FIELD</code> or <code>METHOD</code>.
     *
     * @return <code>true</code> if the Bean Validation provider is allowed to
     *         cascade validation, <code>false</code> otherwise.
     */
     boolean isCascadable(Object traversableObject,
                          Path.Node traversableProperty,
                          Class<?> rootBeanType,
                          Path pathToTraversableObject,
                          ElementType elementType);
}

Hibernate Validator provides two TraversableResolvers out of the box which will be enabled automatically depending on your environment. The first is the DefaultTraversableResolver which will always return true for isReachable() and isTraversable(). The second is the JPATraversableResolver which gets enabled when Hibernate Validator gets used in combination with JPA 2. In case you have to provide your own resolver you can do so again using the Configuration object as seen in Example 5.9, “Providing a custom TraversableResolver”.


Last but not least, there is one more configuration option to discuss, the ConstraintValidatorFactory. The default ConstraintValidatorFactory provided by Hibernate Validator requires a public no-arg constructor to instantiate ConstraintValidator instances (see Section 3.1.2, “The constraint validator”). Using a custom ConstraintValidatorFactory offers for example the possibility to use dependency injection in constraint implementations. The configuration of the custom factory is once more via the Configuration (Example 5.10, “Providing a custom ConstraintValidatorFactory”).


The interface you have to implement is:


Warning

Any constraint implementation relying on ConstraintValidatorFactory behaviors specific to an implementation (dependency injection, no no-arg constructor and so on) are not considered portable.

Note

ConstraintValidatorFactory should not cache instances as the state of each instance can be altered in the initialize method.

The Bean Validation specification provides not only a validation engine, but also a metadata repository for all defined constraints. The following paragraphs are discussing this API. All the introduced classes can be found in the javax.validation.metadata package.

The entry into the metadata API is via Validator.getConstraintsForClass which returns an instance of the BeanDescriptor interface. Using this bean descriptor you can determine whether the specified class hosts any constraints at all via beanDescriptor.isBeanConstrained.

Tip

If a constraint declaration hosted by the requested class is invalid, a ValidationException is thrown.

You can then call beanDescriptor.getConstraintDescriptors to get a set of ConstraintDescriptors representing all class level constraints.

If you are interested in property level constraints, you can call beanDescriptor.getConstraintsForProperty or beanDescriptor.getConstrainedProperties to get a single resp. set of PropertyDescriptors (see Section 6.2, “PropertyDescriptor”).

The PropertyDescriptor interface extends the ElementDescriptor interface and represents constraints on properties of a class. The constraint can be declared on the attribute itself or on the getter of the attribute - provided Java Bean naming conventions are respected. A PropertyDescriptor adds isCascaded (returning true if the property is marked with @Valid) and getPropertyName to the ElementDescriptor functionality.

The ElementDiscriptor interface is the common base class for BeanDescriptor and PropertyDescriptor. Next to the hasConstraints and getConstraintDescriptors methods it also offers access to the ConstraintFinder API which allows you to query the metadata API in a more fine grained way. For example you can restrict your search to constraints described on fields or on getters or a given set of groups. Given an ElementDescriptor instance you just call findConstraints to retrieve a ConstraintFinder instance.


Example 6.1, “Usage of ConstraintFinder” shows an example on how to use the ConstraintFinder API. Interesting are especially the restrictions unorderedAndMatchingGroups and lookingAt(Scope.LOCAL_ELEMENT). The former allows to only return ConstraintDescriptors matching a specified set of groups wheras the latter allows to distinguish between constraint directly specified on the element (Scope.LOCAL_ELEMENT) or constraints belonging to the element but hosted anywhere in the class hierarchy (Scope.HIERARCHY).

Warning

Order is not respected by unorderedAndMatchingGroups, but group inheritance and inheritance via sequence are.

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, as well as the groups the constraint is supposed to be applied on. It also also you to access the pass-through constraint payload (see Example 3.2, “Defining CheckCase constraint annotation”).

Hibernate Validator is intended to be used to implement multi-layered data validation, where constraints are expressed in a single place (the annotated domain model) and checked in various different layers of the application.

The Hibernate Validator jar file is conform to the OSGi specification and can be used within any OSGi container. The following lists represent the packages imported and exported by Hibernate Validator. The classes within the exported packages are considered part of Hibernate Validator public API.

Exported packages

  • org.hibernate.validator

  • org.hibernate.validator.constraints

  • org.hibernate.validator.cfg

  • org.hibernate.validator.cfg.context

  • org.hibernate.validator.cfg.defs

  • org.hibernate.validator.group

  • org.hibernate.validator.messageinterpolation

  • org.hibernate.validator.method

  • org.hibernate.validator.method.metadata

  • org.hibernate.validator.resourceloading

Imported packages

  • javax.persistence.*, [2.0.0,3.0.0), optional

  • javax.validation.*, [1.0.0,2.0.0)

  • javax.xml.*

  • org.xml.sax.*

  • org.jboss.logging.*, [3.1.0,4.0.0)

  • org.joda.time.*, [1.6.0,2.0.0), optional

  • org.jsoup.*, [1.5.2,2.0.0), optional

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

If, for some reason, the feature needs to be disabled, set hibernate.validator.apply_to_ddl to false. See also ???.

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

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

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

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

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

Note

If the beans are not annotated with validation annotations, there is no runtime performance cost.

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


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

In a JPA 1 you will have to create and register Hibernate Validator yourself. In case you are using Hibernate EntityManager you can add a customized version of the BeanValidationEventListener described in Section 7.3.1, “Hibernate event-based validation” to your project and register it manually.

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 7.2, “Usage of Bean Validation within JSF2” shows an example of the f:validateBean tag in a JSF page. For more information refer to the Seam documentation or the JSF 2 specification.


Tip

The integration between JSF 2 and Bean Validation is described in the "Bean Validation Integration" chapter of JSR-314. It is interesting to know that JSF 2 implements a custom MessageInterpolator to ensure ensure proper localization. To encourage the use of the Bean Validation message facility, JSF 2 will per default only display the generated Bean Validation message. This can, however, be configured via the application resource bundle by providing the following configuration ({0} is replaced with the Bean Validation message and {1} is replaced with the JSF component label):

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

The default is:

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

In the following sections we are having a closer look at some of the Hibernate Validator specific features (features which are not part of the Bean Validation specification). This includes the fail fast mode, the programmatic constraint configuration API and boolean composition of composing constraints.

Note

The features described in the following sections are not portable between Bean Validation providers/implementations.

Let's start, however, with a look at the public API of Hibernate Validator. Table 8.1, “Hibernate Validator public API” lists all packages belonging to this API and describes their purpose.

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.

Note

In the following table, when a package is public its not necessarily true for its nested packages.

Table 8.1. Hibernate Validator public API

PackagesDescription
org.hibernate.validatorThis package contains the classes used by the Bean Validation bootstrap mechanism (eg. validation provider, configuration class). For more details see Chapter 5, Bootstrapping.
org.hibernate.validator.cfg, org.hibernate.validator.cfg.context, org.hibernate.validator.cfg.defsWith Hibernate Validator you can define constraints via a fluent API. These packages contain all classes needed to use this feature. In the package org.hibernate.validator.cfg you will find the ConstraintMapping class and in package org.hibernate.validator.cfg.defs all constraint definitions. For more details see Section 8.4, “Programmatic constraint definition”.
org.hibernate.validator.constraints, org.hibernate.validator.constraints.brIn addition to Bean Validation constraints, Hibernate Validator provides some useful custom constraints. These packages contain all custom annotation classes. For more details see Section 2.4.2, “Additional constraints”.
org.hibernate.validator.group, org.hibernate.validator.spi.groupWith Hibernate Validator you can define dynamic default group sequences in function of the validated object state. These packages contain all classes needed to use this feature (GroupSequenceProvider annotation and DefaultGroupSequenceProvider contract). For more details see Section 2.3.2, “Redefining the default group sequence of a class”.
org.hibernate.validator.messageinterpolation, org.hibernate.validator.resourceloading, org.hibernate.validator.spi.resourceloadingThese packages contain the classes related to constraint message interpolation. The first package contains two implementations of MessageInterpolator. The first one, ValueFormatterMessageInterpolator allows to interpolate the validated value into the constraint message, see Section 5.3, “MessageInterpolator”. The second implementation named ResourceBundleMessageInterpolator is the implementation used by default by Hibernate Validator. This implementation relies on a ResourceBundleLocator, see Section 5.3.1, “ResourceBundleLocator”. Hibernate Validator provides different ResourceBundleLocator implementations located in the package org.hibernate.validator.resourceloading.
org.hibernate.validator.method, org.hibernate.validator.method.metadataHibernate Validator provides support for method-level constraints based on appendix C of the Bean Validation specification. The first package contains the MethodValidator interface allowing you to validate method return values and parameters. The second package contains meta data for constraints hosted on parameters and methods which can be retrieved via the MethodValidator.

Note

The public packages of Hibernate Validator fall into two categories: while the actual API parts are intended to be invoked or used by clients (e.g. the API for programmatic constraint declaration or the custom constraints), the SPI (service provider interface) packages contain interfaces which are intended to be implemented by clients (e.g. ResourceBundleLocator).

First off, the fail fast mode. Hibernate Validator allows to return from the current validation as soon as the first constraint violation occurs. This is called the fail fast mode and can be useful for validation of large object graphs where one is only interested whether there is a constraint violation or not. Example 8.1, “Enabling failFast via a property”, Example 8.2, “Enabling failFast at the Configuration level” and Example 8.3, “Enabling failFast at the ValidatorFactory level” show multiple ways to enable the fail fast mode.




The Bean Validation API allows to specify constraints for fields, properties and types. Hibernate Validator goes one step further and allows to place contraint annotations also on method parameters and method return values, thus enabling a programming style known as "Programming by Contract".

More specifically this means that Bean Validation constraints can be used to specify

This approach has several advantages over traditional ways of parameter and return value checking:

Example 8.4, “Using method-level constraints” demonstrates the definition of method-level constraints.


Here the following pre- and postconditions for the rentCar() method are declared:

Using the @Valid annotation it's also possible to define that a cascaded validation of parameter or return value objects shall be performed. An example can be found in Example 8.5, “Cascaded validation of method-level constraints”.


Here all the constraints declared at the Customer type will be evaluated when validating the method parameter and all constraints declared at the returned Rental objects will be evaluated when validating the method's return value.

Special care must be taken when defining parameter constraints in inheritance hierarchies.

When a method is overridden in sub-types method parameter constraints can only be declared at the base type. The reason for this restriction is that the preconditions to be fulfilled by a type's client must not be strengthened in sub-types (which may not even be known to the base type's client). Note that also if the base method doesn't declare any parameter constraints at all, no parameter constraints may be added in overriding methods.

The same restriction applies to interface methods: no parameter constraints may be defined at the implementing method (or the same method declared in sub-interfaces).

If a violation of this rule is detected by the validation engine, a javax.validation.ConstraintDeclarationException will be thrown. In Example 8.6, “Illegal parameter constraint declarations” some examples for illegal parameter constraints declarations are shown.


This rule only applies to parameter constraints, return value constraints may be added in sub-types without any restrictions as it is alright to strengthen the postconditions guaranteed to a type's client.

To validate method-level constraints Hibernate Validator provides the interface org.hibernate.validator.method.MethodValidator.

As shown in Example 8.7, “The MethodValidator interface” this interface defines methods for the evaluation of parameter as well as return value constraints and for retrieving an extended type descriptor providing method constraint related meta data.


To retrieve a method validator get hold of an instance of HV's javax.validation.Validator implementation and unwrap it to MethodValidator as shown in Example 8.8, “Retrieving a MethodValidator instance”.


The validation methods defined on MethodValidator each return a Set<MethodConstraintViolation>. The type MethodConstraintViolation (see Example 8.9, “The MethodConstraintViolation type”) extends javax.validation.ConstraintViolation and provides additional method level validation specific information such as the method and index of the parameter which caused the constraint violation.


Note

The method getParameterName() currently returns synthetic parameter identifiers such as "arg0", "arg1" etc. In a future version of Hibernate Validator support for specifying parameter identifiers might be added.

Typically the validation of method-level constraints is not invoked manually but automatically upon method invocation by an integration layer using AOP (aspect-oriented programming) or similar method interception facilities such as the JDK's java.lang.reflect.Proxy API or CDI ("JSR 299: Contexts and Dependency Injection for the JavaTM EE platform").

If a parameter or return value constraint can't be validated sucessfully such an integration layer typically will throw a MethodConstraintViolationException which similar to javax.validation.ConstraintViolationException contains a set with the occurred constraint violations.

Tip

If you are using CDI you might be interested in the Seam Validation project. This Seam module provides an interceptor which integrates the method validation functionality with CDI.

As outlined in Chapter 6, Metadata API the Bean Validation API provides rich capabilities for retrieving constraint related meta data. Hibernate Validator extends this API and allows to retrieve constraint meta data also for method-level constraints.

Example 8.10, “Retrieving meta data for method-level constraints” shows how to use this extended API to retrieve constraint meta data for the rentCar() method from the RentalStation type.


Refer to the JavaDoc of the package org.hibernate.validator.method.metadata for more details on the extended meta data API.

Another addition to the Bean Validation specification is the ability to configure constraints via a fluent API. This API can be used exclusively or in combination with annotations and xml. If used in combination programmatic constraints are additive to constraints configured via the standard configuration capabilities.

The API is centered around the ConstraintMapping class which can be found in the package org.hibernate.validator.cfg. Starting with the instantiation of a new ConstraintMapping, constraints can be defined in a fluent manner as shown in Example 8.11, “Programmatic constraint definition”.


As you can see constraints can be configured on multiple classes and properties using method chaining. The constraint definition classes NotNullDef, SizeDef and MinDef 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.

For custom constraints you can either create your own definition classes extending ConstraintDef or you can use GenericConstraintDef as seen in Example 8.12, “Programmatic constraint definition using createGeneric()”.


Not only standard class- and property-level constraints but also method constraints can be configured using the API. As shown in Example 8.13, “Programmatic definition of method constraints” methods are identified by their name and their parameters (if there are any). Having selected a method, constraints can be placed on the method's parameters and/or return value.


Using the API it's also possible to mark properties, method parameters and method return values as cascading (equivalent to annotating them with @Valid). An example can be found in Example 8.14, “Marking constraints for cascaded validation”.


Last but not least you can configure the default group sequence or the default group sequence provider of a type as shown in Example 8.15, “Configuration of default group sequence and default group sequence provider”.


Once a ConstraintMapping is set up it has to be passed to the configuration. Since the programmatic API is not part of the official Bean Validation specification you need to get hold of a HibernateValidatorConfiguration instance as shown in Example 8.16, “Creating a Hibernate Validator specific configuration”.


As per Bean Validation specification the constraints of a composed constraint (see Section 3.2, “Constraint composition”) are all combined via a logical AND. This means all of the composing constraints need to return true in order for an overall successful validation. Hibernate Validator offers an extension to this logical AND combination which allows you to compose constraints via a logical OR or NOT. To do so you have to use the ConstraintComposition annotation and the enum CompositionType with its values AND, OR and ALL_FALSE. Example 8.17, “OR composition of constraints” shows how to build a composing constraint where only one of the constraints has to be successful in order to pass the validation. Either the validated string is all lowercased or it is between two and three characters long.


Tip

Using ALL_FALSE as composition type implicitly enforces that only a single violation will get reported in case validation of the constraint composition fails.

Have you ever caught yourself by unintentionally doing things like

  • specifying constraint annotations at unsupported data types (e.g. by annotating a String with @Past)

  • annotating the setter of a JavaBean property (instead of the getter method)

  • annotating static fields/methods with constraint annotations (which is not supported)?

Then the Hibernate Validator Annotation Processor is the right thing for you. It helps preventing such mistakes by plugging into the build process and raising compilation errors whenever constraint annotations are incorrectly used.

Note

You can find the Hibernate Validator Annotation Processor as part of the distribution bundle on Sourceforge or in the JBoss Maven Repository (see Example 1.1, “Configuring the JBoss Maven repository”) under the GAV org.hibernate:hibernate-validator-annotation-processor.

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

When compiling on the command line using javac, specify the JAR hibernate-validator-annotation-processor-4.3.1.Final.jar using the "processorpath" option as shown in the following listing. The processor will be detected automatically by the compiler and invoked during compilation.


There are several options for integrating the annotation processor with Apache Maven. Generally it is sufficient to add the Hibernate Validator Annotation Processor as dependency to your project:


The processor will then be executed automatically by the compiler. This basically works, but comes with the disadavantage that in some cases messages from the annotation processor are not displayed (see MCOMPILER-66).

Another option is using the Maven Annotation Plugin. At the time of this writing the plugin is not yet available in any of the well-known repositories. Therefore you have to add the project's own repository to your settings.xml or pom.xml:


Now disable the standard annotation processing performed by the compiler plugin and configure the annotation plugin by specifying an execution and adding the Hibernate Validator Annotation Processor as plugin dependency (that way the AP is not visible on the project's actual classpath):


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-4.3.1.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:

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-4.3.1.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:

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-4.3.1.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:

  • HV-308: Additional validators registered for a constraint using XML are not evaluated by the annotation processor.

  • Sometimes custom constraints can't be properly evaluated when using the processor within Eclipse. Cleaning the project can help in these situations. This seems to be an issue with the Eclipse JSR 269 API implementation, but further investigation is required here.

  • When using the processor within Eclipse, the check of dynamic default group sequence definitions doesn't work. After further investigation, it seems to be an issue with the Eclipse JSR 269 API implementation.

Last but not least, a few pointers to further information.

A great source for examples is the Bean Validation TCK which is available for anonymous access on GitHub. In particular the TCK's tests might be of interest. The JSR 303 specification itself is also a great way to deepen your understanding of Bean Validation resp. Hibernate Validator.

If you have any further questions to Hibernate Validator or want to share some of your use cases have a look at the Hibernate Validator Wiki and the Hibernate Validator Forum.

In case you would like to report a bug use Hibernate's Jira instance. Feedback is always welcome!