Hibernate.orgCommunity Documentation
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 classes in the following packages are exported by Hibernate Validator and are considered part of the public API - org.hibernate.validator, org.hibernate.validator.constraints, org.hibernate.validator.messageinterpolation and org.hibernate.validator.resourceloading.
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 Table 2.2, “Built-in 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 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 6.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.
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:
Example 6.1. Manual configuration of
BeanValidationEvenListener
<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 6.3.1, “Hibernate event-based validation” can in this
case be configured in persistence.xml.
persistence.xml also defines a node validation-mode
while 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 6.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 6.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.
Example 6.2. Usage of Bean Validation within JSF2
<h:form> <f:validateBean> <h:inputText value=”#{model.property}” /> <h:selectOneRadio value=”#{model.radioProperty}” > ... </h:selectOneRadio> <!-- other input components here --> </f:validateBean> </h:form>
Copyright © 2009, 2010 Red Hat, Inc. & Gunnar Morling