[hibernate-commits] Hibernate SVN: r17577 - in validator/trunk/hibernate-validator/src/main/docbook/en-US: modules and 1 other directory.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Sep 29 07:56:52 EDT 2009
Author: hardy.ferentschik
Date: 2009-09-29 07:56:52 -0400 (Tue, 29 Sep 2009)
New Revision: 17577
Added:
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/furtherreading.xml
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/preface.xml
Modified:
validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/integration.xml
Log:
HV-220
Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml
===================================================================
--- validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml 2009-09-28 16:09:36 UTC (rev 17576)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml 2009-09-29 11:56:52 UTC (rev 17577)
@@ -50,55 +50,9 @@
<toc></toc>
- <preface id="preface" revision="2">
- <title>Preface</title>
+ <xi:include href="modules/preface.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <para>Validating data is a common task that occurs throughout any
- application, from the presentation layer to the persistence layer. Often
- the same validation logic is implemented in each layer, proving time
- consuming and error-prone. To avoid duplication of these validations in
- each layer, developers often bundle validation logic directly into the
- domain model, cluttering domain classes with validation code which is
- really metadata about the class itself.</para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata align="center" contentdepth="" contentwidth="150mm"
- fileref="application-layers.png" scalefit="" />
- </imageobject>
-
- <imageobject role="html">
- <imagedata depth="" fileref="application-layers.png" scalefit="1" />
- </imageobject>
- </mediaobject>
-
- <para>JSR 303 - Bean Validation - defines a metadata model and API for
- entity validation. The default metadata source is annotations, with the
- ability to override and extend the meta-data through the use of XML. The
- API is not tied to a specific application tier or programming model. It is
- specifically not tied to either the web tier or the persistence tier, and
- is available for both server-side application programming, as well as rich
- client Swing application developers.</para>
-
- <para><mediaobject>
- <imageobject role="fo">
- <imagedata align="center" contentdepth="" contentwidth="150mm"
- fileref="application-layers2.png" scalefit="" />
- </imageobject>
-
- <imageobject role="html">
- <imagedata depth="" fileref="application-layers2.png" scalefit="1" />
- </imageobject>
- </mediaobject></para>
-
- <para>Hibernate Validator is the reference implementation of this
- JSR.</para>
- </preface>
-
- <!-- For the alpha release we will just include the getting started section, since the others are work in progress -->
-
- <!--xi:include href="modules/introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /-->
-
<xi:include href="modules/gettingstarted.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
@@ -117,17 +71,6 @@
<xi:include href="modules/integration.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <chapter>
- <title id="chapter-further-reading">Further reading</title>
-
- <para>Last but not least, a few pointers to further information. A great
- source for examples is the Bean Validation TCK which can is available for
- anonymous access in the Hibernate <ulink
- url="http://anonsvn.jboss.org/repos/hibernate/validator/trunk">SVN
- repository</ulink>. Alternatively you can view the tests using <ulink
- url="http://fisheye.jboss.org/browse/Hibernate/beanvalidation/trunk/validation-tck/src/main/java/org/hibernate/jsr303/tck/tests">Hibernate's
- fisheye</ulink> installation. The JSR 303 specification itself is also a
- great way to deepen your understanding of Bean Validation resp. Hibernate
- Validator.</para>
- </chapter>
+ <xi:include href="modules/furtherreading.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
</book>
Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml
===================================================================
--- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml 2009-09-28 16:09:36 UTC (rev 17576)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml 2009-09-29 11:56:52 UTC (rev 17577)
@@ -28,14 +28,11 @@
<chapter id="validator-customconstraints">
<title>Creating custom constraints</title>
- <para>Though the Bean Validation API defines a whole bunch of standard
- constraint annotations such as <classname>@NotNull</classname>,
- <classname>@Size</classname>, <classname>@Min</classname> or
- <classname>@AssertTrue</classname>, one can easily think of situations, for
- which these standard annotations won't suffice. But as the specification was
- designed with extensibility in mind, you are able to create custom
- constraints tailored to your specific validation requirements in a simple
- and timely manner.</para>
+ <para>Though the Bean Validation API defines a whole set of standard
+ constraint annotations one can easily think of situations in which these
+ standard annotations won't suffice. For these cases you are able to create
+ custom constraints tailored to your specific validation requirements in a
+ simple manner.</para>
<section id="validator-customconstraints-simple" revision="1">
<title>Creating a simple constraint</title>
@@ -49,8 +46,7 @@
</listitem>
<listitem>
- <para>Implement a validator, that's able to evaluate that
- annotation</para>
+ <para>Implement a validator</para>
</listitem>
<listitem>
@@ -64,28 +60,36 @@
<para>Let's write a constraint annotation, that can be used to express
that a given string shall either be upper case or lower case. We'll
- apply it later on to ensure, that the <property>licensePlate</property>
- field of the <classname>Car</classname> class from <xref
- linkend="validator-gettingstarted" /> is always an upper-case
- string.</para>
+ apply it later on to the <property>licensePlate</property> field of the
+ <classname>Car</classname> class from <xref
+ linkend="validator-gettingstarted" /> to ensure, that the field is
+ always an upper-case string.</para>
<para>First we need a way to express the two case modes. We might use
<classname>String</classname> constants, but a better way to go is to
use a Java 5 enum for that purpose:</para>
- <programlisting>package com.mycompany;
+ <example>
+ <title>Enum <classname>CaseMode</classname> to express upper vs. lower
+ case</title>
+ <programlisting>package com.mycompany;
+
public enum CaseMode {
UPPER,
LOWER;
}</programlisting>
+ </example>
<para>Now we can define the actual constraint annotation. If you've
never designed an annotation before, this may look a bit scary, but
actually it's not that hard:</para>
- <programlisting>package com.mycompany;
+ <example>
+ <title>Defining CheckCase constraint annotation</title>
+ <programlisting>package com.mycompany;
+
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
@@ -111,6 +115,7 @@
CaseMode value();
}</programlisting>
+ </example>
<para>An annotation type is defined using the <code>@interface</code>
keyword. All attributes of an annotation type are declared in a
@@ -119,29 +124,31 @@
<itemizedlist>
<listitem>
- <para>an attribute "message" that returns the default key for
- creating error messages in case the constraint is violated</para>
+ <para>an attribute <property>message</property> that returns the
+ default key for creating error messages in case the constraint is
+ violated</para>
</listitem>
<listitem>
- <para>an attribute "groups" that allows the specification of
- validation groups, to which this constraint belongs (see <xref
- linkend="validator-usingvalidator-validationgroups" />). This must
- default to an empty array of type
+ <para>an attribute <property>groups</property> that allows the
+ specification of validation groups, to which this constraint belongs
+ (see <xref linkend="validator-usingvalidator-validationgroups" />).
+ This must default to an empty array of type
<classname>Class<?></classname>.</para>
</listitem>
<listitem>
- <para>an attribute "payload" that can be used by clients of the Bean
- Validation API to asign custom payload objects to a constraint. This
- attribute is not used by the API itself.</para>
+ <para>an attribute <classname>payload</classname> that can be used
+ by clients of the Bean Validation API to asign custom payload
+ objects to a constraint. This attribute is not used by the API
+ itself.</para>
</listitem>
</itemizedlist>
<para>Besides those three mandatory attributes we add another one
- allowing for the required case mode to be specified. The name "value" is
- a special one, which can be omitted upon using the annotation, if it is
- the only attribute specified, as e.g. in
+ allowing for the required case mode to be specified. The name
+ <property>value</property> is a special one, which can be omitted upon
+ using the annotation, if it is the only attribute specified, as e.g. in
<code>@CheckCase(CaseMode.UPPER)</code>.</para>
<para>In addition we annotate the annotation type with a couple of
@@ -183,8 +190,12 @@
To do so, we implement the interface ConstraintValidator as shown
below:</para>
- <programlisting>package com.mycompany;
+ <example>
+ <title>Implementing a constraint validator for the constraint
+ <classname>CheckCase</classname></title>
+ <programlisting>package com.mycompany;
+
import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
@@ -208,12 +219,14 @@
}
}</programlisting>
+ </example>
<para>The <classname>ConstraintValidator</classname> interface defines
two type parameters, which we set in our implementation. The first one
specifies the annotation type to be validated (in our example
- CheckCase), the second one the type of elements, which the validator can
- handle (here String).</para>
+ <classname>CheckCase</classname>), the second one the type of elements,
+ which the validator can handle (here
+ <classname>String</classname>).</para>
<para>In case a constraint annotation is allowed at elements of
different types, a <classname>ConstraintValidator</classname> for each
@@ -223,7 +236,8 @@
<para>The implementation of the validator is straightforward. The
<methodname>initialize()</methodname> method gives us access to the
attribute values of the annotation to be validated. In the example we
- store the CaseMode in a field of the validator for further usage.</para>
+ store the <classname>CaseMode</classname> in a field of the validator
+ for further usage.</para>
<para>In the <methodname>isValid()</methodname> method we implement the
logic, that determines, whether a <classname>String</classname> is valid
@@ -244,13 +258,17 @@
<para>Finally we need to specify the error message, that shall be used,
in case a <classname>@CheckCase</classname> constraint is violated. To
- do so, we create a file named
- <filename>ValidationMessages.properties</filename> under
- <filename>src/main/resources</filename> with the following
- content:</para>
+ do so, we add the following to our custom
+ <filename>ValidationMessages.properties</filename> (see also <xref
+ linkend="section-message-interpolation" />)</para>
- <programlisting>com.mycompany.constraints.checkcase=Case mode must be {value}.</programlisting>
+ <example>
+ <title>Defining a custom error message for the
+ <classname>CheckCase</classname> constraint</title>
+ <programlisting>com.mycompany.constraints.CheckCase.message=Case mode must be {value}.</programlisting>
+ </example>
+
<para>If a validation error occurs, the validation runtime will use the
default value, that we specified for the message attribute of the
<classname>@CheckCase</classname> annotation to look up the error
@@ -266,8 +284,12 @@
<property>licensePlate</property> field shall only contain upper-case
strings:</para>
- <programlisting>package com.mycompany;
+ <example id="example-car-with-checkcase">
+ <title>Applying the <classname>CheckCase</classname>
+ constraint</title>
+ <programlisting>package com.mycompany;
+
import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
@@ -295,13 +317,18 @@
//getters and setters ...
}</programlisting>
+ </example>
<para>Finally let's demonstrate in a little test that the
<classname>@CheckCase</classname> constraint is properly
validated:</para>
- <programlisting>package com.mycompany;
+ <example>
+ <title>Testcase demonstrating the <classname>CheckCase</classname>
+ validation</title>
+ <programlisting>package com.mycompany;
+
import static org.junit.Assert.*;
import java.util.Set;
@@ -348,6 +375,7 @@
assertEquals(0, constraintViolations.size());
}
}</programlisting>
+ </example>
</section>
</section>
@@ -355,9 +383,10 @@
<title>Constraint composition</title>
<para>Looking at the <property>licensePlate</property> field of the
- <classname>Car</classname> class, we see three constraint annotations
- already. In complexer scenarios, where even more constraints could be
- applied to one element, this might become a bit confusing easily.
+ <classname>Car</classname> class in <xref
+ linkend="example-car-with-checkcase" />, we see three constraint
+ annotations already. In complexer scenarios, where even more constraints
+ could be applied to one element, this might become a bit confusing easily.
Furthermore, if we had a <property>licensePlate</property> field in
another class, we would have to copy all constraint declarations to the
other class as well, violating the DRY principle.</para>
@@ -368,8 +397,12 @@
<classname>@NotNull</classname>, <classname>@Size</classname> and
<classname>@CheckCase</classname>:</para>
- <programlisting>package com.mycompany;
+ <example>
+ <title>Creating a composing constraint
+ <classname>ValidLicensePlate</classname></title>
+ <programlisting>package com.mycompany;
+
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
@@ -398,6 +431,7 @@
Class<? extends Payload>[] payload() default {};
}</programlisting>
+ </example>
<para>To do so, we just have to annotate the constraint declaration with
its comprising constraints (btw. that's exactly why we allowed annotation
@@ -412,8 +446,12 @@
previous version, where we declared the three constraints directly at the
field itself:</para>
- <programlisting>package com.mycompany;
+ <example>
+ <title>Application of composing constraint
+ <classname>ValidLicensePlate</classname></title>
+ <programlisting>package com.mycompany;
+
public class Car {
@ValidLicensePlate
@@ -422,6 +460,7 @@
//...
}</programlisting>
+ </example>
<para>The set of <classname>ConstraintViolations</classname> retrieved
when validating a <classname>Car</classname> instance will contain an
@@ -432,7 +471,10 @@
<classname>@ReportAsSingleViolation</classname> meta constraint can be
used as follows:</para>
- <programlisting>//...
+ <example>
+ <title>Usage of <classname>@ReportAsSingleViolation</classname></title>
+
+ <programlisting>//...
@ReportAsSingleViolation
public @interface ValidLicensePlate {
@@ -443,5 +485,6 @@
Class<? extends Payload>[] payload() default {};
}</programlisting>
+ </example>
</section>
</chapter>
Added: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/furtherreading.xml
===================================================================
--- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/furtherreading.xml (rev 0)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/furtherreading.xml 2009-09-29 11:56:52 UTC (rev 17577)
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- $Id: bootstrapping.xml 17523 2009-09-16 15:51:58Z hardy.ferentschik $ -->
+<!--
+ ~ Hibernate, Relational Persistence for Idiomatic Java
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
+ ~
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 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">
+<chapter>
+ <title id="chapter-further-reading">Further reading</title>
+
+ <para>Last but not least, a few pointers to further information. A great
+ source for examples is the Bean Validation TCK which can is available for
+ anonymous access in the Hibernate <ulink
+ url="http://anonsvn.jboss.org/repos/hibernate/validator/trunk">SVN
+ repository</ulink>. Alternatively you can view the tests using <ulink
+ url="http://fisheye.jboss.org/browse/Hibernate/beanvalidation/trunk/validation-tck/src/main/java/org/hibernate/jsr303/tck/tests">Hibernate's
+ fisheye</ulink> installation. <ulink
+ url="http://jcp.org/en/jsr/detail?id=303">The JSR 303</ulink> specification
+ itself is also a great way to deepen your understanding of Bean Validation
+ resp. Hibernate Validator.</para>
+
+ <para>If you have any furhter questions to Hibernate Validator or want to
+ share some of your use cases have a look at the <ulink
+ url="http://www.hibernate.org/469.html">Hibernate Validator Wiki</ulink> and
+ the <ulink url="https://forum.hibernate.org/viewforum.php?f=9">Hibernate
+ Validator Forum</ulink>.</para>
+
+ <para>In case you would like to report a bug use <ulink
+ url="http://opensource.atlassian.com/projects/hibernate/browse/HV">Hibernate's
+ Jira</ulink> instance. Feedback is always welcome!</para>
+</chapter>
Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml
===================================================================
--- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml 2009-09-28 16:09:36 UTC (rev 17576)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml 2009-09-29 11:56:52 UTC (rev 17577)
@@ -48,7 +48,11 @@
<listitem>
<para>A properly configured remote repository. Add the following to your
- <filename>settings.xml</filename>: <programlisting><repositories>
+ <filename>settings.xml</filename>: <example>
+ <title>Configuring the JBoss Maven repository in
+ <filename>settings.xml</filename></title>
+
+ <programlisting><repositories>
<repository>
<id>jboss</id>
<url>http://repository.jboss.com/maven2</url>
@@ -59,8 +63,9 @@
<enabled>false</enabled>
</snapshots>
</repository>
-</repositories></programlisting>More information about
- <filename>settings.xml</filename> can be found in the <ulink
+</repositories></programlisting>
+ </example>More information about <filename>settings.xml</filename> can
+ be found in the <ulink
url="http://maven.apache.org/ref/2.0.8/maven-settings/settings.html">Maven
Local Settings Model</ulink>.</para>
</listitem>
@@ -72,12 +77,17 @@
<para>Start by creating new Maven project using the Maven archetype plugin
as follows:</para>
- <para><programlisting>mvn archetype:generate \
+ <para><example>
+ <title>Using Maven's archetype plugin to create a sample project using
+ Hibernate Validator</title>
+
+ <programlisting>mvn archetype:generate \
-DarchetypeCatalog=http://repository.jboss.com/maven2/archetype-catalog.xml \
-DgroupId=com.mycompany \
-DartifactId=beanvalidation-gettingstarted \
-Dversion=1.0-SNAPSHOT \
- -Dpackage=com.mycompany</programlisting></para>
+ -Dpackage=com.mycompany</programlisting>
+ </example></para>
<para>When presented with the list of available archetypes in the JBoss
Maven Repository select the
Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/integration.xml
===================================================================
--- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/integration.xml 2009-09-28 16:09:36 UTC (rev 17576)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/integration.xml 2009-09-29 11:56:52 UTC (rev 17577)
@@ -36,19 +36,23 @@
<section id="validator-checkconstraints-db" revision="2">
<title>Database schema-level validation</title>
- <para>Out of the box, Hibernate Annotations will translate the constraints
- you have defined for your entities into mapping metadata. For example, if
- a property of your entity is annotated <literal>@NotNull</literal>, its
- columns will be declared as <literal>not null</literal> in the DDL schema
- generated by Hibernate.</para>
+ <para>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
+ <literal>@NotNull</literal>, its columns will be declared as <literal>not
+ null</literal> in the DDL schema generated by Hibernate.</para>
- <para>Using hbm2ddl, domain model constraints will be expressed into the
- database schema.</para>
-
<para>If, for some reason, the feature needs to be disabled, set
<literal>hibernate.validator.apply_to_ddl</literal> to
<literal>false</literal>. See also <xref
- linkend="table-builtin-constraints" /></para>
+ linkend="table-builtin-constraints" />.</para>
+
+ <para>You can also limit the DDL constraint generation to a subset of the
+ defined constraints by setting the property
+ <property>org.hibernate.validator.group.ddl</property>. The property
+ specifies the comma seperated, fully specified classnames of the groups a
+ constraint has to be part of in order to be considered for DDL schema
+ generation.</para>
</section>
<section id="validator-checkconstraints-orm">
@@ -61,24 +65,36 @@
<title>Hibernate event-based validation</title>
<para>Hibernate Validator has a built-in Hibernate event listener -
- <classname>org.hibernate.cfg.beanvalidation.BeanValidationEventListener</classname>
- - which is part of Hibernate Annotations. Whenever a
- <literal>PreInsertEvent</literal> or <literal>PreUpdateEvent</literal>
- occurs, the listener will verify all constraints of the entity instance
- and throw an exception if any constraint is violated. Basically, objects
- will be checked before any inserts and before any updates are made by
- Hibernate. This includes changes applied by cascade! This is the most
- convenient and the easiest way to activate the validation process. On
- constraint violation, the event will raise a runtime
+ <ulink
+ url="http://fisheye.jboss.org/browse/Hibernate/core/trunk/annotations/src/main/java/org/hibernate/cfg/beanvalidation/BeanValidationEventListener.java"><classname>org.hibernate.cfg.beanvalidation.BeanValidationEventListener</classname></ulink>
+ - which is part of Hibernate Annotations (as of Hibernate 3.5.x).
+ Whenever a <literal>PreInsertEvent</literal>,
+ <literal>PreUpdateEvent</literal> or
+ <classname>PreDeleteEvent</classname> 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
+ <property>javax.persistence.validation.group.pre-persist</property>,
+ <property>javax.persistence.validation.group.pre-update</property> and
+ <property>javax.persistence.validation.group.pre-remove</property>. The
+ values of these properties are the comma seperated, fully specified
+ class names of the groups to validate. <xref
+ linkend="example-beanvalidationeventlistener-config" /> shows the
+ default values for these properties. In this case they could also be
+ omitted.</para>
+
+ <para>On constraint violation, the event will raise a runtime
<classname>ConstraintViolationException</classname> which contains a set
of <literal>ConstraintViolation</literal>s describing each
failure.</para>
<para>If Hibernate Validator is present in the classpath, Hibernate
- Annotations (or Hibernate EntityManager) will use it transparently. If,
- for some reason, you want to disable this integration, set
- <literal>hibernate.validator.autoregister_listeners</literal> to
- false</para>
+ Annotations (or Hibernate EntityManager) will use it transparently. To
+ avoid validation even though Hibernate Validator is in the classpath set
+ <property>javax.persistence.validation.mode</property> to
+ <constant>none</constant>.</para>
<para><note>
<para>If the beans are not annotated with validation annotations,
@@ -89,86 +105,77 @@
Core, use the following configuration in
<literal>hibernate.cfg.xml</literal>:</para>
- <programlisting><hibernate-configuration>
- ...
+ <example id="example-beanvalidationeventlistener-config">
+ <title>Manual configuration of
+ <classname>BeanValidationEvenListener</classname></title>
+
+ <programlisting><hibernate-configuration>
+ <session-factory>
+ ...
+ <property name="javax.persistence.validation.group.pre-persist">javax.validation.Default</property>
+ <property name="javax.persistence.validation.group.pre-update">javax.validation.Default</property>
+ <property name="javax.persistence.validation.group.pre-remove"></property>
+ </session-factory>
<event type="pre-update">
- <listener
- class="<classname>org.hibernate.cfg.beanvalidation.BeanValidationEventListener</classname>"/>
+ <listener class="<classname>org.hibernate.cfg.beanvalidation.BeanValidationEventListener</classname>"/>
</event>
<event type="pre-insert">
- <listener
- class="<classname>org.hibernate.cfg.beanvalidation.BeanValidationEventListener</classname>"/>
+ <listener class="<classname>org.hibernate.cfg.beanvalidation.BeanValidationEventListener</classname>"/>
</event>
+ <event type="pre-delete">
+ <listener class="<classname>org.hibernate.cfg.beanvalidation.BeanValidationEventListener</classname>"/>
+ </event>
</hibernate-configuration></programlisting>
+ </example>
</section>
- <!--
- <section id="validator-checkconstraints-orm-jpaevent">
- <title>Java Persistence event-based validation</title>
+ <section>
+ <title>JPA </title>
- <para>Hibernate Validator is not tied to Hibernate for event based
- validation: a Java Persistence entity listener is available. Whenever an
- listened entity is persisted or updated, Hibernate Validator will verify
- all constraints of the entity instance and throw an exception if any
- constraint is violated. Basically, objects will be checked before any
- inserts and before any updates made by the Java Persistence provider.
- This includes changes applied by cascade! On constraint violation, the
- event will raise a runtime <classname>InvalidStateException</classname>
- which contains an array of <literal>InvalidValue</literal>s describing
- each failure.</para>
+ <para>If you are using JPA 2 and Hibernate Validator is in the classpath
+ the JPA2 specification requires that Bean Validation gets enabled. The
+ properties
+ <property>javax.persistence.validation.group.pre-persist</property>,
+ <property>javax.persistence.validation.group.pre-update</property> and
+ <property>javax.persistence.validation.group.pre-remove</property> as
+ described in <xref
+ linkend="validator-checkconstraints-orm-hibernateevent" /> can in this
+ case be configured in <filename>persistence.xml</filename>.
+ <filename>persistence.xml</filename> also defines a node validation-mode
+ while can be set to <constant>AUTO</constant>,
+ <constant>CALLBACK</constant>, <constant>NONE</constant>. The default is
+ <constant>AUTO</constant>. </para>
- <para>Here is how to make a class validatable:</para>
-
- <programlisting>@Entity
- at EntityListeners( JPAValidateListener.class )
-public class Submarine {
- ...
-}</programlisting>
-
- <para><note>
- <para>Compared to the Hibernate event, the Java Persistence listener
- has two drawbacks. You need to define the entity listener on every
- validatable entity. The DDL generated by your provider will not
- reflect the constraints.</para>
- </note></para>
+ <para>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
+ <classname>BeanValidationEventListener</classname> described in <xref
+ linkend="validator-checkconstraints-orm-hibernateevent" /> to your
+ project and register it manually.</para>
</section>
- -->
</section>
<section id="section-presentation-layer">
<title>Presentation layer validation</title>
- <para>When working with JSF and <productname>JBoss Seam</productname>, one
- can triggers the validation process at the presentation layer using Seam's
- JSF tags <literal><s:validate></literal> and
- <literal><s:validateAll/></literal>, letting the constraints be
- expressed on the model, and the violations presented in the view</para>
+ <para>When working with JSF2 or <productname>JBoss Seam</productname> and
+ Hibernate Validator (Bean Validation) is present in the runtime
+ environment validation is triggered for every field in the application.
+ <xref linkend="example-jsf" /> 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.</para>
- <programlisting><h:form>
- <div>
- <h:messages/>
- </div>
- <emphasis role="bold"><s:validateAll></emphasis>
- <div>
- Country:
- <h:inputText value="#{location.country}" required="true"/>
- </div>
- <div>
- Zip code:
- <h:inputText value="#{location.zip}" required="true"/>
- </div>
- <div>
- <h:commandButton/>
- </div>
- <emphasis role="bold"></s:validateAll></emphasis>
-</h:form></programlisting>
+ <example id="example-jsf2">
+ <title>Usage of Bean Validation within JSF2</title>
- <para>Going even further, and adding <productname>Ajax4JSF</productname>
- to the loop will bring client side validation with just a couple of
- additional JSF tags, again without validation definition
- duplication.</para>
-
- <para>Check the <ulink url="http://www.jboss.com/products/seam">JBoss
- Seam</ulink> documentation for more information.</para>
+ <programlisting><h:form>
+ <emphasis role="bold"><f:validateBean></emphasis>
+ <h:inputText value=”#{model.property}” />
+ <h:selectOneRadio value=”#{model.radioProperty}” > ... </h:selectOneRadio>
+ <!-- other input components here -->
+ <emphasis role="bold"></f:validateBean></emphasis>
+</h:form>
+</programlisting>
+ </example>
</section>
</chapter>
Added: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/preface.xml
===================================================================
--- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/preface.xml (rev 0)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/preface.xml 2009-09-29 11:56:52 UTC (rev 17577)
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- $Id: bootstrapping.xml 17523 2009-09-16 15:51:58Z hardy.ferentschik $ -->
+<!--
+ ~ Hibernate, Relational Persistence for Idiomatic Java
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
+ ~
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 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">
+ <preface id="preface" revision="2">
+ <title>Preface</title>
+
+ <para>Validating data is a common task that occurs throughout any
+ application, from the presentation layer to the persistence layer. Often
+ the same validation logic is implemented in each layer, proving time
+ consuming and error-prone. To avoid duplication of these validations in
+ each layer, developers often bundle validation logic directly into the
+ domain model, cluttering domain classes with validation code which is
+ really metadata about the class itself.</para>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" contentdepth="" contentwidth="150mm"
+ fileref="application-layers.png" scalefit="" />
+ </imageobject>
+
+ <imageobject role="html">
+ <imagedata depth="" fileref="application-layers.png" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+
+ <para>JSR 303 - Bean Validation - defines a metadata model and API for
+ entity validation. The default metadata source is annotations, with the
+ ability to override and extend the meta-data through the use of XML. The
+ API is not tied to a specific application tier or programming model. It is
+ specifically not tied to either the web tier or the persistence tier, and
+ is available for both server-side application programming, as well as rich
+ client Swing application developers.</para>
+
+ <para><mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" contentdepth="" contentwidth="150mm"
+ fileref="application-layers2.png" scalefit="" />
+ </imageobject>
+
+ <imageobject role="html">
+ <imagedata depth="" fileref="application-layers2.png" scalefit="1" />
+ </imageobject>
+ </mediaobject></para>
+
+ <para>Hibernate Validator is the reference implementation of this
+ JSR.</para>
+ </preface>
+
+
More information about the hibernate-commits
mailing list