diff --git a/annotations/src/main/docbook/en/modules/additionalmodules.xml b/annotations/src/main/docbook/en/modules/additionalmodules.xml index e0648bfa3d..601ad99799 100644 --- a/annotations/src/main/docbook/en/modules/additionalmodules.xml +++ b/annotations/src/main/docbook/en/modules/additionalmodules.xml @@ -1,4 +1,4 @@ - + - - + Additional modules Hibernate Annotations mainly focus on persistence metadata. The - project also have a nice integration with two Hibernate modules. + project also have a nice integration with some external modules.
- Hibernate Validator + Bean Validation + + Bean Validation standardizes how to define and declare domain model + level constraints. You can, for example, express that a property should + never be null, that the account balance should be strictly positive, etc. + These domain model constraints are declared in the bean itself by + annotating its properties. Bean Validation can then read them and check + for constraint violations. The validation mechanism can be executed in + different layers in your application without having to duplicate any of + these rules (presentation layer, data access layer). Following the DRY + principle, Bean Validation and its reference implementation Hibernate + Validator has been designed for that purpose. + + The integration between Hibernate and Bean Validation works at two + levels. First, it is able to check in-memory instances of a class for + constraint violations. Second, it can apply the constraints to the + Hibernate metamodel and incorporate them into the generated database + schema. + + Each constraint annotation is associated to a validator + implementation responsible for checking the constraint on the entity + instance. A validator can also (optionally) apply the constraint to the + Hibernate metamodel, allowing Hibernate to generate DDL that expresses the + constraint. With the appropriate event listener, you can execute the + checking operation on inserts, updates and deletes done by + Hibernate. + + When checking instances at runtime, Hibernate Validator returns + information about constraint violations in a set of + ConstraintViolations. Among other information, the + ConstraintViolation contains an error description + message that can embed the parameter values bundle with the annotation + (eg. size limit), and message strings that may be externalized to a + ResourceBundle. + +
+ Adding Bean Validation + + To enable the Hibernate - Bean Validation integration, simply add + a Bean Validation provider (preferably Hibernate Validation 4) in your + classpath. +
+ +
+ Configuration + + By default, no configuration is necessary. + + The Default group is validated on entity + insert and update and the database model is updated accordingly based on + the Default group as well. + + You can customize the Bean Validation integration by setting the + validation mode. Use the + javax.persistence.validation.mode property and set it + up for example in your persistence.xml file. + Several options are possible: + + + + auto (default): enable integration between + Bean Validation and Hibernate (callback and ddl generation) only if + Bean Validation is present in the classpath. + + + + none: disable all integration between Bean + Validation and Hibernate + + + + callback: only validate entities when they + are either inserted, updated or deleted. An exception is raised if + no Bean Validation provider is present in the classpath. + + + + ddl: only apply constraints to the database + schema when generated by Hibernate. An exception is raised if no + Bean Validation provider is present in the classpath. This value is + not defined by the Java Persistence spec and is specific to + Hibernate. + + + + + You can use both callback and + ddl together by setting the property to + callback, dll + + <persistence ...> + <persistence-unit ...> + ... + <properties> + <property name="javax.persistence.validation.mode" + value="callback, ddl"/> + </properties> + </persistence-unit> +</persistence> + + This is equivalent to auto except that if no + Bean Validation provider is present, an exception is raised. + + + If you want to validate different groups during insertion, update + and deletion, use: + + + + javax.persistence.validation.group.pre-persist: + groups validated when an entity is about to be persisted (default to + Default) + + + + javax.persistence.validation.group.pre-update: + groups validated when an entity is about to be updated (default to + Default) + + + + javax.persistence.validation.group.pre-remove: + groups validated when an entity is about to be deleted (default to + no group) + + + + org.hibernate.validator.group.ddl: groups + considered when applying constraints on the database schema (default + to Default) + + + + Each property accepts the fully qualified class names of the + groups validated separated by a comma (,) + + + Using custom groups for validation + + <persistence ...> + <persistence-unit ...> + ... + <properties> + <property name="javax.persistence.validation.group.pre-update" + value="javax.validation.group.Default, com.acme.group.Strict"/> + <property name="javax.persistence.validation.group.pre-remove" + value="com.acme.group.OnDelete"/> + <property name="org.hibernate.validator.group.ddl" + value="com.acme.group.DDL"/> + </properties> + </persistence-unit> +</persistence> + + + + You can set these properties in + hibernate.cfg.xml, + hibernate.properties or programmatically. + +
+ +
+ Catching violations + + If an entity is found to be invalid, the list of constraint + violations is propagated by the + ConstraintViolationException which exposes the + set of ConstraintViolations. + + This exception is wrapped into an + HibernateException or a + PersistenceException. Note that generally, + catchable violation are validated at a higher level (for example in Seam + / JSF 2 via the JSF - Bean Validation integration or in your business + layer by explicitly calling Bean Validation). + + An application code will rarely be looking for a + ConstraintViolationException raised by Hibernate. + This exception should be treated as fatal and the persistence context + should be discarded (EntityManager or + Session). +
+ +
+ Database schema + + Hibernate uses Bean Validation constraints to generate an accurate + database schema: + + + + @NotNull leads to a not null column + (unless it conflicts with components or table inheritance) + + + + @Size.max leads to a + varchar(max) definition for Strings + + + + @Min, @Max lead + to column checks (like value <= max) + + + + @Digits leads to the definition of + precision and scale (ever wondered which is which? It's easy now + with @Digits :) ) + + + + These constraints can be declared directly on the entity + properties or indirectly by using constraint composition. +
+
+ +
+ Hibernate Validator 3 + + + We strongly encourage you to use Hibernate Validator 4 and the + Bean Validation integration. Consider Hibernate Validator 3 as + legacy. +
Description