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 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.
The Java Service Provider mechanism used by Bean Validation to automatically
discover validation providers doesn't work in an OSGi environment. To solve this,
you have to provide a custom ValidationProviderResolver. See
Section 5.2, “ValidationProviderResolver”
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.
When lazy loaded associations are supposed to be validated it is recommended to place the constraint on the getter of the association. Hibernate replaces lazy loaded associations with proxy instances which get initialized/loaded when requested via the getter. If, in such a case, the constraint is placed on field level the actual proxy instance is used which will lead to validation errors.
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.
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 7.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 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.
Example 7.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>
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}Copyright © 2009 - 2011 Red Hat, Inc. & Gunnar Morling