From hibernate-commits at lists.jboss.org Wed Sep 2 09:14:22 2009 Content-Type: multipart/mixed; boundary="===============7242698202605995176==" MIME-Version: 1.0 From: hibernate-commits at lists.jboss.org To: hibernate-commits at lists.jboss.org Subject: [hibernate-commits] Hibernate SVN: r17466 - validator/trunk/hibernate-validator/src/main/docbook/en-US/modules. Date: Wed, 02 Sep 2009 09:14:22 -0400 Message-ID: <200909021314.n82DEMo3010174@svn01.web.mwc.hst.phx2.redhat.com> --===============7242698202605995176== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: hardy.ferentschik Date: 2009-09-02 09:14:22 -0400 (Wed, 02 Sep 2009) New Revision: 17466 Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/custo= mconstraints.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/getti= ngstarted.xml 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/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-09-02 03:06:15 UTC (rev 17465) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/cust= omconstraints.xml 2009-09-02 13:14:22 UTC (rev 17466) @@ -64,9 +64,9 @@ Let's write a constraint annotation, that can be used to expre= ss that a given string shall either be upper case or lower case. We'll apply it later on to ensure, that the licensePlate - field of the Car class from the Getting started chapter = is - always an upper-case string. + field of the Car class from is always an upper-case + string. = First we need a way to express the two case modes. We might use String constants, but a better way to go is to Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/module= s/gettingstarted.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/gett= ingstarted.xml 2009-09-02 03:06:15 UTC (rev 17465) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gett= ingstarted.xml 2009-09-02 13:14:22 UTC (rev 17466) @@ -29,25 +29,25 @@ Getting started = This chapter will show you how to get started with Hibernate Valid= ator - - the reference implementation (RI) of the Bean Validation API. Be sure = to - fulfill the following prerequisites in order to proceed: + - the reference implementation (RI) of Bean Validation. For the following + quickstart you need: = - As the Bean Validation API expresses constraints by the means = of - annotations, Java version 5 or later must be installed + A JDK >=3D 5 = - As Apache Maven will - be used as build tool in the following, Maven must be installed and a - functioning internet connection is required to allow Maven to downlo= ad - all dependent libraries + Apache Maven = - Once Maven is installed you should configure your remote - repository by adding the following to your + A functioning Internet connection (Maven has to download all + required libraries) + + + + A properly configured remote repository. Add the following to = your settings.xml: <repositories&= gt; <repository> <id>jboss</id> @@ -81,9 +81,11 @@ = When presented with the list of available archetypes in the JBoss Maven Repository select the - hibernate-validator-quickstart-archetype and conf= irm - the properties. Maven will create your project in the directory - beanvalidation-gettingstarted. Change into this directory and run: + hibernate-validator-quickstart-archetype. After + downloading all dependencies confirm the settings by just pressing ent= er. + Maven will create your project in the directory + beanvalidation-gettingstarted. Change into this + directory and run: = mvn testYou should see some compiling and testing action taking place. Time to look at the actual @@ -93,30 +95,35 @@
Applying constraints to a model class = - Open the project in the IDE of your choice (for Eclipse, you may - type mvn eclipse:eclipse to create a standard Eclipse project - configuration OR you may use the M2Eclipse plugin. NetBe= ans - has great Maven support too, as described here) and = open - the class Car: + Open the project in the IDE of your choice and have a look at the + class Car: = - package com.mycompany; + + Eclipse users can type mvn eclipse:eclipse to create a standard + Eclipse project configuration or they use the M2Eclipse plugin. Net= Beans + and Intellij have great built-in Maven support. + = + + Class Car annotated with constraints + + package com.mycompany; + import javax.validation.constraints.Min; import javax.validation.constraints.NotNull; import javax.validation.constraints.Size; = public class Car { = - @NotNull + @NotNull private String manufacturer; = - @NotNull - @Size(min =3D 2, max =3D 14) + @NotNull + @Size(min =3D 2, max =3D 14) private String licensePlate; = - @Min(2) + @Min(2) private int seatCount; = public Car(String manufacturer, String licencePlate, int seatCount) { @@ -127,12 +134,10 @@ } = //getters and setters ... - -} - - @NotNull, @Size and - @Min are so-called constraint annotions, that we - use to declare constraints, which shall be applied to the fields of a +} + @NotNull, @Size + and @Min are so-called constraint annotations, = that + we use to declare constraints, which shall be applied to the fields of= a Car instance: = @@ -150,12 +155,15 @@ = - To perform a validation of these constraints, we use the - Validator interface defined by the specificatio= n. - Let's try it in a test for our Car class: + To perform a validation of these constraints, we use a + Validator instance. Let's have a look at the + CarTest class: = - package com.mycompany; + + Class CarTest showing validation examples = + package com.mycompany; + import static org.junit.Assert.*; = import java.util.Set; @@ -187,8 +195,7 @@ validator.validate(car); = assertEquals(1, constraintViolations.size()); - assertEquals( - "may not be null", constraintViolations.iterator().next().getM= essage()); + assertEquals("may not be null", constraintViolations.iterator().ne= xt().getMessage()); } = @Test @@ -200,8 +207,7 @@ validator.validate(car); = assertEquals(1, constraintViolations.size()); - assertEquals( - "size must be between 2 and 14", constraintViolations.iterator= ().next().getMessage()); + assertEquals("size must be between 2 and 14", constraintViolations= .iterator().next().getMessage()); } = @Test @@ -213,8 +219,7 @@ validator.validate(car); = assertEquals(1, constraintViolations.size()); - assertEquals( - "must be greater than or equal to 2", constraintViolations.ite= rator().next().getMessage()); + assertEquals("must be greater than or equal to 2", constraintViola= tions.iterator().next().getMessage()); } = @Test @@ -227,20 +232,21 @@ = assertEquals(0, constraintViolations.size()); } -} +} + = In the setUp() method we get a - Validator object from the + Validator instance from the ValidatorFactory. A Validator instance is thread-safe and may be re= used multiple times, therefore we store it as field of our test class. We c= an - use the validator now to validate the different car objects in the test + use the validator now to validate the different car instances in the t= est methods. = The validate() method returns a set of ConstraintViolation objects, which we can itera= te - through in order to see which validation errors occured. The first thr= ee - test methods show some expected constraint violations: + in order to see which validation errors occurred. The first three test + methods show some expected constraint violations: = @@ -259,21 +265,20 @@ = - If the object could be validated successfully (as in - carIsValid()), + If the object could be validated successfully, validate() returns an empty set. = Note that we only use classes from the package - javax.validation, which stems from the Bean Validat= ion - standard API. As we don't reference any classes of the RI directly, it - would be no problem to switch to another implementation of the API, sh= ould - that need arise. + javax.validation from the Bean Validation API. As we + don't reference any classes of the RI directly, it would be no problem= to + switch to another implementation of the API, should that need + arise.
=
Where to go next? = That concludes our 5 minute tour through the world of the Bean - Validation RI. + Validation RI.
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 03:06:15 UTC (rev 17465) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usin= gvalidator.xml 2009-09-02 13:14:22 UTC (rev 17466) @@ -25,16 +25,39 @@ - Object validation + Basic validation = + In this chapter we will see in more detail how to use Bean Validat= ion + to validate constraints for a given entity model. We will also learn whi= ch + default constraints the specification provides and which additional + constraints are only provided by Hibernate Validator. Let's start with h= ow + to add constraints to an entity. +
Annotating your model = - Using the Bean Validation API validation constraints are express= ed - via Java 5 annotations. In this section we show how to annotate your - object model with Bean Validation constraint annotations. + Constraints in Bean Validation are expressed via Java annotation= s. + In this section we show how to annotate an object model with these + annotations. We have to differentiate between three different type of + constraint annotations - class-, field- and property-level + annotations. = + + Not all constraints can be placed on any of these levels. In + fact all the default constraints defined by Bean Validation cannot= be + places at class level. The java.lang.annotation.Target annotation + placed on the constraint annotation itself determines on which + elements a constraint can be placed. See also + +
+ Class-level + annotations + + TODO +
+ +
Field level annotations = One way for expressing constraints is to annotate the fields o= f a @@ -116,12 +139,6 @@
=
- Class-level annotations - - TODO -
- -
Annotated interfaces and super-classes = When validating an object that implements an interface or exte= nds --===============7242698202605995176==--