From hibernate-commits at lists.jboss.org Wed Sep 2 14:50:51 2009
Content-Type: multipart/mixed; boundary="===============4860812212034012161=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r17470 -
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules.
Date: Wed, 02 Sep 2009 14:50:51 -0400
Message-ID: <200909021850.n82IopCd009617@svn01.web.mwc.hst.phx2.redhat.com>
--===============4860812212034012161==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Author: hardy.ferentschik
Date: 2009-09-02 14:50:50 -0400 (Wed, 02 Sep 2009)
New Revision: 17470
Modified:
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/using=
validator.xml
Log:
HV-220
Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/module=
s/usingvalidator.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usin=
gvalidator.xml 2009-09-02 15:47:47 UTC (rev 17469)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usin=
gvalidator.xml 2009-09-02 18:50:50 UTC (rev 17470)
@@ -446,97 +446,174 @@
Validator methods
=
The Validator interface contains three
- methods that can be used to validate entire objects or only single
- object properties.
+ methods that can be used to validate entire object instances or only
+ single properties of an instance.
=
All of these methods return a
- Set<ConstraintViolation>, which will be
+ Set<ConstraintViolation>. The set will =
be
empty, if the validation succeeded. Otherwise a
ConstraintViolation object for each violated
- constraint will be contained.
+ constraint will be added to the set.
=
All the validation methods have a var-args parameter which can=
be
used to specify, which validation groups shall be considered when
- performing the validation. If the parameter is not specified (as in =
the
- following examples) the default validation group will be used. We wi=
ll
- go into more detail on the topic of validation groups in the following
- section.
+ performing the validation. If the parameter is not specified the def=
ault
+ validation group (javax.validation.Default) w=
ill
+ be used. We will go into more detail on the topic of validation grou=
ps
+ in
=
- validate()
+ <methodname>validate</methodname>
=
Use the validate() method to perform
- validation of all constraints of a given object. The following lis=
ting
- shows an example:
+ validation of all constraints of a given entity instance. The
+ following listing shows an example:
=
- ValidatorFactory factory =3D Validation.buildDefau=
ltValidatorFactory();
+
+ Usage of
+ <methodname>Validator.validate()</methodname>
+
+ ValidatorFactory factory =3D Validation.buildDef=
aultValidatorFactory();
Validator validator =3D factory.getValidator();
=
Car car =3D new Car(null);
=
-Set<ConstraintViolation<Car>> constraintViolations =3D
- validator.validate(car);
+Set<ConstraintViolation<Car>> constraintViolations =3D validat=
or.validate(car);
=
assertEquals(1, constraintViolations.size());
-assertEquals(
- "may not be null", constraintViolations.iterator().next().getMessage()=
);
+assertEquals("may not be null", constraintViolations.iterator().next().get=
Message());
+
=
- validateProperty()
+ <methodname>validateProperty</methodname>
=
With help of the validateProperty()=
a
- single named property of a given object can be validated:
+ single named property of a given object can be validated. The prop=
erty
+ name is the JavaBeans property name. @Valid is not honored by this
+ method.
=
- Validator validator =3D Validation.buildDefaultVal=
idatorFactory().getValidator();
+
+ Usage of
+ <methodname>Validator.validateProperty()</methodname>
=
+ Validator validator =3D Validation.buildDefaultV=
alidatorFactory().getValidator();
+
Car car =3D new Car(null);
=
-Set<ConstraintViolation<Car>> constraintViolations =3D
- validator.validateProperty(car, "manufacturer");
+Set<ConstraintViolation<Car>> constraintViolations =3D validat=
or.validateProperty(car, "manufacturer");
=
assertEquals(1, constraintViolations.size());
-assertEquals(
- "may not be null", constraintViolations.iterator().next().getMessage()=
);
+assertEquals("may not be null", constraintViolations.iterator().next().get=
Message());
+
+ Validator.validateProperty is for
+ example used in the integration of Bean Validation into JSF
+ 2.
+
=
- validateValue()
+ <methodname>validateValue</methodname>
=
Using the validateValue() method you
can check, whether a single property of a given class can be valid=
ated
successfully, if the property had the specified value:
=
- Validator validator =3D Validation.buildDefaultVal=
idatorFactory().getValidator();
+
+ Usage of
+ <methodname>Validator.validateValue()</methodname>
=
-Set<ConstraintViolation<Car>> constraintViolations =3D
- validator.validateValue(Car.class, "manufacturer", null);
+ Validator validator =3D Validation.buildDefaultV=
alidatorFactory().getValidator();
=
+Set<ConstraintViolation<Car>> constraintViolations =3D validat=
or.validateValue(Car.class, "manufacturer", null);
+
assertEquals(1, constraintViolations.size());
-assertEquals(
- "may not be null", constraintViolations.iterator().next().getMessage()=
);
-
+assertEquals("may not be null", constraintViolations.iterator().next().get=
Message());
=
-
- getConstraintsForClass()
-
- TODO
+ @Valid is not honored by this method.
+
=
- Working with ConstraintViolations
+ <classname>ConstraintViolation</classname>s explained
=
- TODO: Message interpolation?
+ Now it is time to have a closer look at what a failing validat=
ion
+ returns - a ConstraintViolation. Using the
+ different methods of a ConstraintViolation
+ instance a lot of useful information about the reason of the validat=
ion
+ failure can be determined.
+
+
+ The various <classname>ConstraintViolation</classname>
+ methods
+
+
+
+
+ Method
+
+ Usage
+
+
+
+ getMessage()
+
+ The interpolated error message.
+
+
+
+ getMessageTemplate()
+
+ The non-interpolated error message.
+
+
+
+ getRootBean()
+
+ The root bean being validated.
+
+
+
+ getRootBeanClass()
+
+ The class of the root bean being validated.
+
+
+
+ getLeafBean()
+
+ If a bean constraint, the bean instance the constrain=
t is
+ applied on. If a property constraint, the bean instance host=
ing
+ the property the constraint is applied on.
+
+
+
+ getPropertyPath()
+
+ The property path to the value from root bean.
+
+
+
+ getInvalidValue()
+
+ The value failing to pass the constraint.
+
+
+
+ getConstraintDescriptor()
+
+ Constraint metadata reported to fail.
+
+
+
+
=
Using groups
=
-
-
Group sequences
=
--===============4860812212034012161==--