From hibernate-commits at lists.jboss.org Mon Mar 30 06:45:23 2009 Content-Type: multipart/mixed; boundary="===============2327145421076838855==" MIME-Version: 1.0 From: hibernate-commits at lists.jboss.org To: hibernate-commits at lists.jboss.org Subject: [hibernate-commits] Hibernate SVN: r16227 - validator/trunk/hibernate-validator/src/main/docbook/en-US/modules. Date: Mon, 30 Mar 2009 06:45:19 -0400 Message-ID: --===============2327145421076838855== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: hardy.ferentschik Date: 2009-03-30 06:45:18 -0400 (Mon, 30 Mar 2009) New Revision: 16227 Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/custo= mconstraints.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/using= validator.xml Log: latest doc changes Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/module= s/customconstraints.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/cust= omconstraints.xml 2009-03-27 17:12:01 UTC (rev 16226) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/cust= omconstraints.xml 2009-03-30 10:45:18 UTC (rev 16227) @@ -314,7 +314,7 @@ assertEquals(1, constraintViolations.size()); assertEquals( "Case mode must be UPPER.", = - constraintViolations.iterator().next().getInterpolatedMessage(= )); + constraintViolations.iterator().next().getMessage()); } = @Test @@ -552,7 +552,7 @@ assertEquals(1, constraintViolations.size()); assertEquals( "Passenger count must be less than or equal to seat count.", - constraintViolations.iterator().next().getInterpolatedMessage(= )); + constraintViolations.iterator().next().getMessage()); } = @Test 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-03-27 17:12:01 UTC (rev 16226) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usin= gvalidator.xml 2009-03-30 10:45:18 UTC (rev 16227) @@ -25,33 +25,409 @@ - Using the Validator API + Object validation using the Bean Validation API = + TODO: outline of the chapter. Should this be placed before "Creating custom + constraints"? +
- Annotate your model + Annotating your model = - Field, Getter + Using the Bean Validation API validation constraints are express= ed + via Java 5 annotations. In this section it will be shown how to annota= te + your object model with Bean Validation constraint annotations. + +
+ Field validation + + One way for expressing constraints is to annotate the fields o= f a + class with constraint annotations. The following listing shows a sim= ple + example: + + package com.mycompany; + +import javax.validation.constraints.NotNull; + +public class Car { + + @NotNull + private String manufacturer; + + public Car(String manufacturer) { + + this.manufacturer =3D manufacturer; + } + +} +
+ +
+ Property validation + + If your model class adheres to the JavaBeans + standard (meaning basically, there are getter and setter methods for= the + properties of the class), it is also possible to annotate the proper= ties + of a bean class instead of its fields. Note that the property's gett= er + method has to be annotated, not its setter method: + + package com.mycompany; + +import javax.validation.constraints.AssertTrue; +import javax.validation.constraints.NotNull; + +public class Car { + + private String manufacturer; + + private boolean isRegistered; + = + = + public Car(String manufacturer, boolean isRegistered) { + super(); + this.manufacturer =3D manufacturer; + this.isRegistered =3D isRegistered; + } + + @NotNull + public String getManufacturer() { + return manufacturer; + } + + public void setManufacturer(String manufacturer) { + this.manufacturer =3D manufacturer; + } + + @AssertTrue + public boolean isRegistered() { + return isRegistered; + } + + public void setRegistered(boolean isRegistered) { + this.isRegistered =3D isRegistered; + } + +} + + Generally it is considered a good practice to stick either with + field OR with property annotation within one model class for the sak= e of + readability. It is not recommended to annotate a field AND the + accompanying getter method as this would cause the field to be valid= ated + twice. +
+ +
+ Class-level annotations + + TODO: Should this be mentioned here? +
+ +
+ Annotated interfaces and super-classes + + When validating an object that implements some interface or + extends another class, all constraint annotations at the properties = of + that interface or parent class apply in the same manner as the + constraint annotations at the validated object itself. To make things + clearer let's have a look at the following example: + + //class Car +package com.mycompany; + +import javax.validation.constraints.NotNull; + +public class Car { + + private String manufacturer; + = + public Car(String manufacturer) { + this.manufacturer =3D manufacturer; + } + + @NotNull + public String getManufacturer() { + return manufacturer; + } + + public void setManufacturer(String manufacturer) { + this.manufacturer =3D manufacturer; + } + +} + +//class RentalCar +package com.mycompany; + +import javax.validation.constraints.NotNull; + +public class RentalCar extends Car { + + private String rentalStation; + = + public RentalCar(String manufacturer, String rentalStation) { + super(manufacturer); + this.rentalStation =3D rentalStation; + } + = + @NotNull + public String getRentalStation() { + return rentalStation; + } + + public void setRentalStation(String rentalStation) { + this.rentalStation =3D rentalStation; + } + +} + + Our well-known class Car is now extended by RentalCar with an + additional property, rentalStation. If an instance of RentalCar is + validated now, not only the @NotNull constraint at the rentalStation + property would be validated, but also the constraint at manufacturer + from the parent class. + + The same would hold true, if Car was an interface, that is + implemented by RentalCar. + + Constraint annotations are aggregated if methods are overridde= n. + If RentalCar would override the getManufacturer() method from Car any + constraints annotated at the overriding method would be evaluated in + addition to the @NotNull constraint from the super-class. +
+ +
+ Validating object graphes + + The Bean Validation API does not only allow to validate single + objects but also complete object graphs. To do so just annotate a fi= eld + or property representing a reference to another object with + @Valid. + + If the parent object is validated, all objects referenced by a + field/property annotated with @Valid will be validated as well (as w= ill + be their children etc.). The following shows a simple example: + + //class Person +package com.mycompany; + +import javax.validation.constraints.NotNull; + +public class Person { + + @NotNull + private String name; + = + public Person(String name) { + super(); + this.name =3D name; + } + + public String getName() { + return name; + } + + public void setName(String name) { + this.name =3D name; + } + = +} + +//class car +package com.mycompany; + +import javax.validation.Valid; +import javax.validation.constraints.NotNull; + +public class Car { + + @NotNull + @Valid + private Person driver; + = + public Car(Person driver) { + + this.driver =3D driver; + } + + //getters and setters ... + +} + + If an instance of Car is validated, the referenced Person obje= ct + will be validated as well, as the driver field is annotated with @Va= lid. + Therefore the validation of a Car will fail if the name field of the + referenced Person instance is null. + + Object graph validation also works for collection-typed fields. + That means any attributes that are + + + + arrays + + + + of type java.lang.Iterable (and therfore its direct or + indirect derivations Collection, List and Set) + + + + of type java.util.Map + + + + can be annotated with @Valid, which will cause each contained + element to be validated, when the parent object is validated. + + package com.mycompany; + +import java.util.ArrayList; +import java.util.List; + +import javax.validation.Valid; +import javax.validation.constraints.Min; +import javax.validation.constraints.NotNull; +import javax.validation.constraints.Size; + +import org.hibernate.validation.constraints.NotEmpty; + +public class Car { + + @NotNull + @Valid + private List<Person> passengers =3D new ArrayList<Person>(= ); + = + public Car(List<Person> passengers) { + + this.passengers =3D passengers; + } + + //getters and setters ... + +} + + If a Car instance is validated now, a ConstraintValidation wil= l be + raised, if any of the Person objects contained in the passenger list= has + a null name. +
=
- Object validation + Using the Validator API = - Plain, Use of @Valid + The Validator interface is the main entry point to the Bean + Validation API. In the following we first will show how to obtain + Validator instances using the bootstrapping mechanism that the API + provides. Afterwards you'll learn how to use the different methods of = the + Validator interfaces followed by an overview of the information that + ConstraintViolation instances offer. + +
+ Obtaining Validator instances + + TODO: DefaultFactory, customization, note on thread safety +
+ +
+ Validator methods + + The Validator interface contains three methods that can be use= d to + validate entire objects or only single object properties. + + All of these methods return a Set<ConstraintViolation>, + which will be empty, if the validation succeeded. Otherwise a + ConstraintViolation object for each violated constraint will be + contained. + + 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. + +
+ validate() + + Use the validate() method to perform validation of all + constraints of a given object. The following listing shows an + example: + + ValidatorFactory factory =3D Validation.buildDefau= ltValidatorFactory(); +Validator validator =3D factory.getValidator(); + +Car car =3D new Car(null); + +Set<ConstraintViolation<Car>> constraintViolations =3D + validator.validate(car); + +assertEquals(1, constraintViolations.size()); +assertEquals( + "may not be null", constraintViolations.iterator().next().getMessage()= ); +
+ +
+ validateProperty() + + With help of the validateProperty() a single named property = of a + given object can be validated: + + Validator validator =3D Validation.buildDefaultVal= idatorFactory().getValidator(); + +Car car =3D new Car(null); + +Set<ConstraintViolation<Car>> constraintViolations =3D + validator.validateProperty(car, "manufacturer"); + +assertEquals(1, constraintViolations.size()); +assertEquals( + "may not be null", constraintViolations.iterator().next().getMessage()= ); +
+ +
+ validateValue() + + Using the validateValue() method you can check, whether a si= ngle + property of a given class can be validated successfully, if the + property had the specified value: + + Validator validator =3D Validation.buildDefaultVal= idatorFactory().getValidator(); + +Set<ConstraintViolation<Car>> constraintViolations =3D + validator.validateValue(Car.class, "manufacturer", null); + +assertEquals(1, constraintViolations.size()); +assertEquals( + "may not be null", constraintViolations.iterator().next().getMessage()= ); +
+ +
+ getConstraintsForClass() + + TODO: Should this be mentioned here? +
+
+ +
+ Working with ConstraintViolations + + TODO: Message interpolation? +
=
Validation groups = -
- Group sequences +
+ Group sequences = - -
+ +
=
- Validating method parameters - - +
--===============2327145421076838855==--