[hibernate-commits] Hibernate SVN: r16524 - core/trunk/annotations/src/main/docbook/en/modules.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Thu May 7 17:35:18 EDT 2009
Author: epbernard
Date: 2009-05-07 17:35:18 -0400 (Thu, 07 May 2009)
New Revision: 16524
Modified:
core/trunk/annotations/src/main/docbook/en/modules/additionalmodules.xml
Log:
ANN-827 ANN-828 doc for Hibernate Validation
Modified: core/trunk/annotations/src/main/docbook/en/modules/additionalmodules.xml
===================================================================
--- core/trunk/annotations/src/main/docbook/en/modules/additionalmodules.xml 2009-05-07 21:34:21 UTC (rev 16523)
+++ core/trunk/annotations/src/main/docbook/en/modules/additionalmodules.xml 2009-05-07 21:35:18 UTC (rev 16524)
@@ -1,4 +1,4 @@
-<?xml version='1.0' encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
@@ -22,18 +22,242 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="additionalmodules">
<title>Additional modules</title>
<para>Hibernate Annotations mainly focus on persistence metadata. The
- project also have a nice integration with two Hibernate modules.</para>
+ project also have a nice integration with some external modules.</para>
<section>
- <title>Hibernate Validator</title>
+ <title>Bean Validation</title>
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>When checking instances at runtime, Hibernate Validator returns
+ information about constraint violations in a set of
+ <classname>ConstraintViolation</classname>s. Among other information, the
+ <classname>ConstraintViolation</classname> 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
+ <classname>ResourceBundle</classname>.</para>
+
<section>
+ <title>Adding Bean Validation</title>
+
+ <para>To enable the Hibernate - Bean Validation integration, simply add
+ a Bean Validation provider (preferably Hibernate Validation 4) in your
+ classpath. </para>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+
+ <para>By default, no configuration is necessary.</para>
+
+ <para>The <classname>Default</classname> group is validated on entity
+ insert and update and the database model is updated accordingly based on
+ the <classname>Default</classname> group as well.</para>
+
+ <para>You can customize the Bean Validation integration by setting the
+ validation mode. Use the
+ <literal>javax.persistence.validation.mode</literal> property and set it
+ up for example in your <filename>persistence.xml</filename> file.
+ Several options are possible:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>auto</literal> (default): enable integration between
+ Bean Validation and Hibernate (callback and ddl generation) only if
+ Bean Validation is present in the classpath.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>none</literal>: disable all integration between Bean
+ Validation and Hibernate</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>callback</literal>: 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>ddl</literal>: 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.</para>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>You can use both <literal>callback</literal> and
+ <literal>ddl</literal> together by setting the property to
+ <literal>callback, dll</literal></para>
+
+ <programlisting><persistence ...>
+ <persistence-unit ...>
+ ...
+ <properties>
+ <property name="javax.persistence.validation.mode"
+ value="callback, ddl"/>
+ </properties>
+ </persistence-unit>
+</persistence></programlisting>
+
+ <para>This is equivalent to <literal>auto</literal> except that if no
+ Bean Validation provider is present, an exception is raised.</para>
+ </note>
+
+ <para>If you want to validate different groups during insertion, update
+ and deletion, use:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>javax.persistence.validation.group.pre-persist</literal>:
+ groups validated when an entity is about to be persisted (default to
+ <classname>Default</classname>)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>javax.persistence.validation.group.pre-update</literal>:
+ groups validated when an entity is about to be updated (default to
+ <classname>Default</classname>)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>javax.persistence.validation.group.pre-remove</literal>:
+ groups validated when an entity is about to be deleted (default to
+ no group)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>org.hibernate.validator.group.ddl</literal>: groups
+ considered when applying constraints on the database schema (default
+ to <classname>Default</classname>)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Each property accepts the fully qualified class names of the
+ groups validated separated by a comma (,)</para>
+
+ <example>
+ <title>Using custom groups for validation</title>
+
+ <programlisting><persistence ...>
+ <persistence-unit ...>
+ ...
+ <properties>
+ <property name="<literal>javax.persistence.validation.group.pre-update</literal>"
+ value="javax.validation.group.Default, com.acme.group.Strict"/>
+ <property name="<literal>javax.persistence.validation.group.pre-remove</literal>"
+ value="com.acme.group.OnDelete"/>
+ <property name="<literal>org.hibernate.validator.group.ddl</literal>"
+ value="com.acme.group.DDL"/>
+ </properties>
+ </persistence-unit>
+</persistence></programlisting>
+ </example>
+
+ <note>
+ <para>You can set these properties in
+ <filename>hibernate.cfg.xml</filename>,
+ <filename>hibernate.properties</filename> or programmatically.</para>
+ </note>
+ </section>
+
+ <section>
+ <title>Catching violations</title>
+
+ <para>If an entity is found to be invalid, the list of constraint
+ violations is propagated by the
+ <classname>ConstraintViolationException</classname> which exposes the
+ set of <classname>ConstraintViolation</classname>s.</para>
+
+ <para>This exception is wrapped into an
+ <classname>HibernateException</classname> or a
+ <classname>PersistenceException</classname>. 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).</para>
+
+ <para>An application code will rarely be looking for a
+ <classname>ConstraintViolationException</classname> raised by Hibernate.
+ This exception should be treated as fatal and the persistence context
+ should be discarded (<classname>EntityManager</classname> or
+ <classname>Session</classname>).</para>
+ </section>
+
+ <section>
+ <title>Database schema</title>
+
+ <para>Hibernate uses Bean Validation constraints to generate an accurate
+ database schema:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><classname>@NotNull</classname> leads to a not null column
+ (unless it conflicts with components or table inheritance)</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>@Size.max</classname> leads to a
+ <literal>varchar(max)</literal> definition for Strings</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>@Min</classname>, <classname>@Max</classname> lead
+ to column checks (like <code>value <= max</code>) </para>
+ </listitem>
+
+ <listitem>
+ <para><classname>@Digits</classname> leads to the definition of
+ precision and scale (ever wondered which is which? It's easy now
+ with <classname>@Digits</classname> :) )</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>These constraints can be declared directly on the entity
+ properties or indirectly by using constraint composition.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Hibernate Validator 3</title>
+
+ <warning>
+ <para>We strongly encourage you to use Hibernate Validator 4 and the
+ Bean Validation integration. Consider Hibernate Validator 3 as
+ legacy.</para>
+ </warning>
+
+ <section>
<title>Description</title>
<para>Annotations are a very convenient and elegant way to specify
More information about the hibernate-commits
mailing list