Out of the box, Hibernate (as of version 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 Table 2.2, “Bean Validation constraints” and Table 2.3, “Custom constraints”.

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

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

<hibernate-configuration>

    <session-factory>

        ...

        <property name="javax.persistence.validation.group.pre-persist">

            javax.validation.groups.Default

        </property>

        <property name="javax.persistence.validation.group.pre-update">

            javax.validation.groups.Default

        </property>

        <property name="javax.persistence.validation.group.pre-remove"></property>

        ...

        <event type="pre-update">

            <listener class="org.hibernate.cfg.beanvalidation.BeanValidationEventListener"/>

        </event>

        <event type="pre-insert">

            <listener class="org.hibernate.cfg.beanvalidation.BeanValidationEventListener"/>

        </event>

        <event type="pre-delete">

            <listener class="org.hibernate.cfg.beanvalidation.BeanValidationEventListener"/>

        </event>

    </session-factory>

</hibernate-configuration>

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 10.1.2, “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 10.1.2, “Hibernate event-based validation” to your project and register it manually.

CDI's dependency injection mechanism makes it very easy to retrieve ValidatorFactory and Validator instances and use them in your managed beans. Just annotate instance fields of your bean with @javax.inject.Inject as shown in Example 10.3, “Retrieving validator factory and validator via @Inject”.

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


@ApplicationScoped

public class RentalStation {


    @Inject

    private ValidatorFactory validatorFactory;


    @Inject

    private Validator validator;


    //...

}

The injected beans are the default validator factory and validator instances. In order to configure them - e.g. to use a custom message interpolator - you can use the Bean Validation XML descriptors as discussed in Chapter 7, Configuring via XML.

If you are working with several Bean Validation providers you can make sure that factory and validator from Hibernate Validator are injected by annotating the injection points with the @HibernateValidator qualifier which is demonstrated in Example 10.4, “Using the @HibernateValidator qualifier annotation”.

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


@ApplicationScoped

public class RentalStation {


    @Inject

    @HibernateValidator

    private ValidatorFactory validatorFactory;


    @Inject

    @HibernateValidator

    private Validator validator;


    //...

}

Via @Inject you also can inject dependencies into constraint validators and other Bean Validation objects such as MessageInterpolator implementations etc.

Example 10.5, “Constraint validator with injected bean” demonstrates how an injected CDI bean is used in a ConstraintValidator implementation to determine whether the given constraint is valid or not. As the example shows, you also can work with the @PostConstruct and @PreDestroy callbacks to implement any required construction and destruction logic.

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


public class ValidLicensePlateValidator

        implements ConstraintValidator<ValidLicensePlate, String> {


    @Inject

    private VehicleRegistry vehicleRegistry;


    @PostConstruct

    public void postConstruct() {

        //do initialization logic...

    }


    @PreDestroy

    public void preDestroy() {

        //do destruction logic...

    }


    @Override

    public void initialize(ValidLicensePlate constraintAnnotation) {

    }


    @Override

    public boolean isValid(String licensePlate, ConstraintValidatorContext constraintContext) {

        return vehicleRegistry.isValidLicensePlate( licensePlate );

    }

}

The method interception facilities of CDI allow for a very tight integration with Bean Validation's method validation functionality. Just put constraint annotations to the parameters and return values of the executables of your CDI beans and they will be validated automatically before (parameter constraints) and after (return value constraints) a method or constructor is invoked.

Note that no explicit interceptor binding is required, instead the required method validation interceptor will automatically be registered for all managed beans with constrained methods and constructors.

You can see an example in Example 10.6, “CDI managed beans with method-level constraints”.

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


@ApplicationScoped

public class RentalStation {


    @Valid

    public RentalStation() {

        //...

    }


    @NotNull

    @Valid

    public Car rentCar(

            @NotNull Customer customer,

            @NotNull @Future Date startDate,

            @Min(1) int durationInDays) {

        //...

    }


    @NotNull

    List<Car> getAvailableCars() {

        //...

    }

}

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


@RequestScoped

public class RentCarRequest {


    @Inject

    private RentalStation rentalStation;


    public void rentCar(String customerId, Date startDate, int duration) {

        //causes ConstraintViolationException

        rentalStation.rentCar( null, null, -1 );

    }

}

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


@ApplicationScoped

@ValidateOnExecution(type = ExecutableType.ALL)

public class RentalStation {


    @Valid

    public RentalStation() {

        //...

    }


    @NotNull

    @Valid

    @ValidateOnExecution(type = ExecutableType.NONE)

    public Car rentCar(

            @NotNull Customer customer,

            @NotNull @Future Date startDate,

            @Min(1) int durationInDays) {

        //...

    }


    @NotNull

    public List<Car> getAvailableCars() {

        //...

    }

}

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


@ValidateOnExecution(type = ExecutableType.ALL)

public interface RentalStation {


    @NotNull

    @Valid

    Car rentCar(

            @NotNull Customer customer,

            @NotNull @Future Date startDate,

            @Min(1) int durationInDays);

}

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


@ApplicationScoped

@ValidateOnExecution(type = ExecutableType.IMPLICIT)

public class ExpressRentalStation implements RentalStation {


    @Override

    public Car rentCar(Customer customer, Date startDate, @Min(1) int durationInDays) {

        //...

    }

}