Chapter 2. Validation step by step

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.

2.1. Defining constraints

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.

Note

Not all constraints can be placed on all of these levels. In fact, none of the default constraints defined by Bean Validation can be placed at class level. The java.lang.annotation.Target annotation in the constraint annotation itself determines on which elements a constraint can be placed. See Chapter 3, Creating custom constraints for more information.

2.1.1. Field-level constraints

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

Example 2.1. Field level constraint

package com.mycompany;

import javax.validation.constraints.NotNull;

public class Car {

    @NotNull
    private String manufacturer;

    @AssertTrue
    private boolean isRegistered;

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

When using field level constraints field access strategy is used to access the value to be validated. This means the instance variable directly independed of the access type.

Note

The access type (private, protected or public) does not matter.

Note

Static fields and properties cannot be validated.

2.1.2. Property-level constraints

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.

Example 2.2. Property level constraint

package com.mycompany;

import javax.validation.constraints.AssertTrue;
import javax.validation.constraints.NotNull;

public class Car {

    private String manufacturer;

    private boolean isRegistered;
      
    public Car(String manufacturer, boolean isRegistered) {
        super();
        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;
    }
}

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.

Tip

It is recommended to stick either to field or property annotation 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.

2.1.3. Class-level constraints

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 we it is enough to know that PassengerCount will ensure that there cannot be more passengers in a car than there are seats.

Example 2.3. Class level constraint

package com.mycompany;

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

@PassengerCount
public class Car {

    @NotNull
    private String manufacturer;

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

    @Min(2)
    private int seatCount;
    
    private List<Person> passengers;
    
    public Car(String manufacturer, String licencePlate, int seatCount) {
        this.manufacturer = manufacturer;
        this.licensePlate = licencePlate;
        this.seatCount = seatCount;
    }

    //getters and setters ...
}

2.1.4. Constraint inheritance

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:

Example 2.4. Constraint inheritance using RentalCar

package com.mycompany;

import javax.validation.constraints.NotNull;

public class RentalCar extends Car {

    private String rentalStation;
    
    public RentalCar(String manufacturer, String rentalStation) {
        super(manufacturer);
        this.rentalStation = rentalStation;
    }
    
    @NotNull
    public String getRentalStation() {
        return rentalStation;
    }

    public void setRentalStation(String rentalStation) {
        this.rentalStation = rentalStation;
    }
}

Our well-known class Car from ??? 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.

2.1.5. Object graphs

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

Example 2.5. Class Person

package com.mycompany;

import javax.validation.constraints.NotNull;

public class Person {

    @NotNull
    private String name;
    
    public Person(String name) {
        super();
        this.name = name;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

Example 2.6. Adding a driver to the car

package com.mycompany;

import javax.validation.Valid;
import javax.validation.constraints.NotNull;

public class Car {

    @NotNull
    @Valid
    private Person driver;
    
    public Car(Person driver) {
        this.driver = driver;
    }

    //getters and setters ...
}

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.

Example 2.7. Car with a list of passengers

package com.mycompany;

import java.util.ArrayList;
import java.util.List;

import javax.validation.Valid;
import javax.validation.constraints.NotNull;

public class Car {

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

    public Car(List<Person> passengers) {
        this.passengers = passengers;
    }

    //getters and setters ...
}

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.

2.2. Validating constraints

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.

2.2.1. Obtaining a `Validator` instance

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

Example 2.8. Validation.buildDefaultValidatorFactory()

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

For other ways of obtaining a Validator instance see Chapter 5, Bootstrapping. For now we just want to see how we can use the Validator instance to validate entity instances.

2.2.2. Validator methods

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.Default) will be used. We will go into more detail on the topic of validation groups in Section 2.3, “Validating groups”

2.2.2.1. `validate`

Use the validate() method to perform validation of all constraints of a given entity instance (see Example 2.9, “Usage of Validator.validate()” ).

Example 2.9. Usage of Validator.validate()

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

Car car = new Car(null);

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

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

2.2.2.2. `validateProperty`

With help of the validateProperty() a single named property of a given object can be validated. The property name is the JavaBeans property name.

Example 2.10. Usage of Validator.validateProperty()

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

Car car = new Car(null);

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

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

Validator.validateProperty is for example used in the integration of Bean Validation into JSF 2 (see Section 6.3, “Presentation layer validation”).

2.2.2.3. `validateValue`

Using the validateValue() method you can check, whether a single property of a given class can be validated successfully, if the property had the specified value:

Example 2.11. Usage of Validator.validateValue()

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

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

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

Note

@Valid is not honored by validateProperty() or validateValue().

2.2.3. `ConstraintViolation` methods

Now it is time to have a closer look at what a ConstraintViolation. Using the different methods of ConstraintViolation a lot of useful information about the cause of the validation failure can be determined. Table 2.1, “The various ConstraintViolation methods” gives an overview of these methods:

Table 2.1. The various ConstraintViolation methods

Method	Usage	Example (refering to Example 2.9, “Usage of Validator.validate()”)
`getMessage()`	The interpolated error message.	may not be null
`getMessageTemplate()`	The non-interpolated error message.	{javax.validation.constraints.NotNull.message}
`getRootBean()`	The root bean being validated.	car
`getRootBeanClass()`	The class of the root bean being validated.	Car.class
`getLeafBean()`	If a bean constraint, the bean instance the constraint is applied on. If a property constraint, the bean instance hosting the property the constraint is applied on.	car
`getPropertyPath()`	The property path to the value from root bean.
`getInvalidValue()`	The value failing to pass the constraint.	passengers
`getConstraintDescriptor()`	Constraint metadata reported to fail.

2.2.4. Message interpolation

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.

2.3. Validating groups

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 @NotNullconstraint on name. Since no group is specified for this annotation its default group is javax.validation.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.Default is assumed.

Example 2.12. Person

public class Person {
    @NotNull
    private String name;

    public Person(String name) {
        this.name = name;
    }
    // getters and setters ...
}

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.

Note

The Bean Validation specification does not enforce that groups have to be interfaces. Non interface classes could be used as well, but we recommend to stick to interfaces.

Example 2.13. Driver

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

Example 2.14. Group interfaces

public interface DriverChecks {
}

public interface CarChecks {
}

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.

Example 2.15. Car

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

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.

2.3.1. Group sequences

By default, constraints are evaluated in no particular order and this regardless of which groups they belong to. In some situations, however, it is useful to control the order of the constraints evaluation. 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 constraints fails in a sequenced group none of the constraints of the follwoing groups in the sequence get validated.

Example 2.17. Interface with @GroupSequence

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

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

Example 2.18. Usage of a group sequence

@Test
public void testOrderedChecks() {
    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() );
}

2.3.2. Redefining the default group sequence of a class

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 class, place a @GroupSequence annotation on the class. The defined groups in the annotation express the sequence of groups that substitute Default for this class. Example 2.19, “RentalCar” introduces a new class RentalCar with a redfined default group. With this definition the check for all three groups can be rewritten as seen in Example 2.20, “testOrderedChecksWithRedefinedDefault”.

Example 2.19. RentalCar

@GroupSequence({ RentalCar.class, CarChecks.class })
public class RentalCar extends Car {
    public RentalCar(String manufacturer, String licencePlate, int seatCount) {
        super( manufacturer, licencePlate, seatCount );
    }
}

Example 2.20. testOrderedChecksWithRedefinedDefault

@Test
public void testOrderedChecksWithRedefinedDefault() {
    RentalCar rentalCar = new RentalCar( "Morris", "DD-AB-123", 2 );
    rentalCar.setPassedVehicleInspection( true );

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

    assertEquals( 0, validator.validate( rentalCar, Default.class, DriverChecks.class ).size() );
}

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 should be added!

2.4. Built-in constraints

Hibernate Validator implements all of the default constraints specified in Bean Validation as well as some custom ones. Table 2.2, “Built-in constraints” list all constraints available in Hibernate Validator.

Table 2.2. Built-in constraints

Annotation	Part of Bean Validation Specification	Apply on	Use	Hibernate Metadata impact
@AssertFalse	yes	field/property	check that the annotated element is `false`.	none
@AssertTrue	yes	field/property	check that the annotated element is `true`.	none
@DecimalMax	yes	field/property. Supported types are `BigDecimal`, `BigInteger`, `String`, `byte`, `short`, `int`, `long` and the respective wrappers of the primitive types.	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
@DecimalMin	yes	field/property. Supported types are `BigDecimal`, `BigInteger`, `String`, `byte`, `short`, `int`, `long` and the respective wrappers of the primitive types.	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=)	yes	field/property. Supported types are `BigDecimal`, `BigInteger`, `String`, `byte`, `short`, `int`, `long` and the respective wrappers of the primitive types.	Check whether the property is a number having up to `integer` digits and `fraction` fractional digits.	Define column precision and scale.
@Email	no	field/property. Needs to be a string.	Check whether the specified string is a valid email address.	none
@Future	yes	field/property. Supported types are `java.util.Date` and `java.util.Calendar`.	Checks whether the annotated date is in the future.	none
@Length(min=, max=)	no	field/property. Needs to be a string.	Validate that the annotated string is between `min` and `max` included.	none
@Max	yes	field/property. Supported types are `BigDecimal`, `BigInteger`, `String`, `byte`, `short`, `int`, `long` and the respective wrappers of the primitive types.	Checks whether the annotated value is less than or equal to the specified maximum.	Add a check constraint on the column.
@Min	yes	field/property. Supported types are `BigDecimal`, `BigInteger`, `String`, `byte`, `short`, `int`, `long` and the respective wrappers of the primitive types.	Check whether the annotated value is higher than or equal to the specified minimum.	Add a check constraint on the column.
@NotNull	yes	field/property	Check that the annotated value is not `null.`	Column(s) are not null.
@NotEmpty	no	field/property. Needs to be a string.	Check if the string is not `null` nor empty.	none
@Null	yes	field/property	Check that the annotated value is `null.`	none
@Past	yes	field/property. Supported types are `java.util.Date` and `java.util.Calendar`.	Checks whether the annotated date is in the past.	none
@Pattern(regex=, flag=)	yes	field/property. Needs to be a string.	Check if the annotated string match the regular expression `regex`.	none
@Range(min=, max=)	no	field/property. Supported types are `BigDecimal`, `BigInteger`, `String`, `byte`, `short`, `int`, `long` and the respective wrappers of the primitive types.	Check whether the annotated value lies between (inclusive) the specified minimum and maximum.	none
@Size(min=, max=)	yes	field/property. Supported types are `String`, `Collection`, `Map` and `arrays`.	Check if the annotated element size is between min and max (inclusive).	Column length will be set to max.
@Valid	yes	field/property	Perform validation recursively on the associated object.	none

Note

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

In some cases these built-in constraints will not fulfill your requirements. In this case you can literally in a minute write your own constraints. We will discuss this in Chapter 3, Creating custom constraints