[hibernate-commits] Hibernate SVN: r17480 - validator/trunk/hibernate-validator/src/main/docbook/en-US/modules.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Fri Sep 4 10:31:32 EDT 2009
Author: hardy.ferentschik
Date: 2009-09-04 10:31:32 -0400 (Fri, 04 Sep 2009)
New Revision: 17480
Modified:
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/integration.xml
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml
Log:
HV-220
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-04 12:30:03 UTC (rev 17479)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/integration.xml 2009-09-04 14:31:32 UTC (rev 17480)
@@ -49,28 +49,31 @@
<para>If, for some reason, the feature needs to be disabled, set
<literal>hibernate.validator.apply_to_ddl</literal> to
- <literal>false</literal>.</para>
+ <literal>false</literal>. See also <xref
+ linkend="table-builtin-constraints" /></para>
</section>
<section id="validator-checkconstraints-orm">
<title>ORM integration</title>
<para>Hibernate Validator integrates with both Hibernate and all pure Java
- Persistence providers</para>
+ Persistence providers.</para>
<section id="validator-checkconstraints-orm-hibernateevent" revision="1">
<title>Hibernate event-based validation</title>
- <para>Hibernate Validator has two built-in Hibernate event listeners.
- Whenever a <literal>PreInsertEvent</literal> or
- <literal>PreUpdateEvent</literal> occurs, the listeners 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 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 <classname>InvalidStateException</classname> which
- contains an array of <literal>InvalidValue</literal>s describing each
+ <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
+ <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
@@ -92,11 +95,11 @@
...
<event type="pre-update">
<listener
- class="org.hibernate.validator.event.ValidateEventListener"/>
+ class="<classname>org.hibernate.cfg.beanvalidation.BeanValidationEventListener</classname>"/>
</event>
<event type="pre-insert">
<listener
- class="org.hibernate.validator.event.ValidateEventListener"/>
+ class="<classname>org.hibernate.cfg.beanvalidation.BeanValidationEventListener</classname>"/>
</event>
</hibernate-configuration></programlisting>
</section>
@@ -133,40 +136,6 @@
</section>
<section>
- <title>Application-level validation</title>
-
- <para>Hibernate Validator can be applied anywhere in your application
- code.</para>
-
- <programlisting>ClassValidator personValidator = new ClassValidator( Person.class );
-ClassValidator addressValidator = new ClassValidator( Address.class, ResourceBundle.getBundle("messages", Locale.ENGLISH) );
-
-InvalidValue[] validationMessages = addressValidator.getInvalidValues(address);</programlisting>
-
- <para>The first two lines prepare the Hibernate Validator for class
- checking. The first one relies upon the error messages embedded in
- Hibernate Validator (see <xref
- linkend="validator-defineconstraints-error" />), the second one uses a
- resource bundle for these messages. It is considered a good practice to
- execute these lines once and cache the validator instances.</para>
-
- <para>The third line actually validates the <literal>Address</literal>
- instance and returns an array of <literal>InvalidValue</literal>s. Your
- application logic will then be able to react to the failure.</para>
-
- <para>You can also check a particular property instead of the whole bean.
- This might be useful for property per property user interaction</para>
-
- <programlisting>ClassValidator addressValidator = new ClassValidator( Address.class, ResourceBundle.getBundle("messages", Locale.ENGLISH) );
-
-//only get city property invalid values
-InvalidValue[] validationMessages = addressValidator.getInvalidValues(address, "city");
-
-//only get potential city property invalid values
-InvalidValue[] validationMessages = addressValidator.getPotentialInvalidValues("city", "Paris")</programlisting>
- </section>
-
- <section>
<title>Presentation layer validation</title>
<para>When working with JSF and <productname>JBoss Seam</productname>, one
Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml
===================================================================
--- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml 2009-09-04 12:30:03 UTC (rev 17479)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml 2009-09-04 14:31:32 UTC (rev 17480)
@@ -633,17 +633,21 @@
<title>Using groups</title>
<para>Groups allow you to restrict the set of constraints applied during
- validation. This allows for example for wizard like validation where for
- each step only a specified subset of the defined constraints get
- validated. The groups targeted are passed as var-args parameters to
+ validation. This allows for example for wizard like validation where in
+ each step only a specified subset of constraints get validated. The groups
+ targeted are passed as var-args parameters to
<methodname>validate</methodname>,
<methodname>validateProperty</methodname> and
<methodname>validateValue</methodname>. When more than one group is
requested, the order in which the groups are evaluated is not
deterministic. If no group is specified the default group
<classname>javax.validation.Default</classname> is assumed. Let's have a
- look at a slightly extended <classname>Car</classname> with
- <classname>Driver</classname> example.</para>
+ look at an extended <classname>Car</classname> with
+ <classname>Driver</classname> example. First we have the class
+ <classname>Person</classname> which has a <classname>@NotNull
+ </classname>constraint on name. Since no group is specified for this
+ annoation its default groups is
+ <classname>javax.validation.Default</classname>.</para>
<para><example>
<title>Person</title>
@@ -658,7 +662,16 @@
// getters and setters ...
}</programlisting>
- </example><example>
+ </example>Next we have the class <classname>Driver</classname> extending
+ <classname>Person</classname>. Here we are adding the properties
+ <property>age</property> and <property>hasDrivingLicense</property>. In
+ order to drive you must be at least 18 (<classname>@Min(18)</classname>)
+ and you must have a driving license (<classname>@AssertTrue</classname>).
+ Both of consraints defined on these properties belong to the group
+ <classname>DriverChecks</classname>. As you can the group is just a simple
+ interface. Using interfaces makes the group feature type safe and allows
+ for easy refactoring. It also means that groups can inherit from each
+ other by simple class inheritance.<example>
<title>Driver</title>
<programlisting>public class Driver extends Person {
@@ -685,6 +698,17 @@
}
}</programlisting>
</example><example>
+ <title>The actual group interfaces</title>
+
+ <programlisting>public interface DriverChecks {
+}
+
+public interface CarChecks {
+}</programlisting>
+ </example>Last but not least we add the property
+ <property>passedVehicleInspection</property> to the
+ <classname>Car</classname> class indecating whether a car passed the road
+ worthy tests.<example>
<title>Car</title>
<programlisting>public class Car {
@@ -710,16 +734,17 @@
this.seatCount = seatCount;
}
}</programlisting>
- </example><example>
- <title>The actual group interfaces</title>
-
- <programlisting>public interface DriverChecks {
-}
-
-
-public interface CarChecks {
-}</programlisting>
- </example><example>
+ </example>Overall three different groups are used in our example.
+ <property>Person.name</property>, <property>Car.manufacturer</property>,
+ <property>Car.licenseplate</property> and
+ <property>Car.seatCount</property> all belong to the
+ <classname>Default</classname> group. <property>Driver.age</property> and
+ <property>Driver.hasDrivingLicense</property> belong to
+ <classname>DriverChecks</classname> and last but not least
+ <property>Car.passedVehicleInspection</property> belongs to the group
+ <classname>CarChecks</classname>. The following example shows how passing
+ different group combinations to the Validator.validate method result in
+ different validation results.<example>
<title>Drive away</title>
<programlisting>public class GroupTest {
@@ -774,6 +799,12 @@
some situations to control the order of constraints evaluation. There
are often scenarios where a preliminary set of constraints should be
evaluated prior to other constraints. ...</para>
+
+ <section>
+ <title>Redefining the default group sequence of a class</title>
+
+ <para></para>
+ </section>
</section>
</section>
@@ -849,7 +880,7 @@
the string representation of the max value according to the
<classname>BigDecimal</classname> string representation.</entry>
- <entry></entry>
+ <entry>none</entry>
</row>
<row>
@@ -869,7 +900,7 @@
the string representation of the min value according to the
<classname>BigDecimal</classname> string representation.</entry>
- <entry></entry>
+ <entry>none</entry>
</row>
<row>
More information about the hibernate-commits
mailing list