Hibernate SVN: r16227 - validator/trunk/hibernate-validator/src/main/docbook/en-US/modules.
by hibernate-commits＠lists.jboss.org
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/customconstraints.xml
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml
Log:
latest doc changes
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-03-27 17:12:01 UTC (rev 16226)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.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/modules/usingvalidator.xml
===================================================================
--- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml 2009-03-27 17:12:01 UTC (rev 16226)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml 2009-03-30 10:45:18 UTC (rev 16227)
@@ -25,33 +25,409 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="validator-usingvalidator">
- <title>Using the Validator API</title>
+ <title>Object validation using the Bean Validation API</title>
+ <para>TODO: outline of the chapter. Should this be placed before <link
+ lang="" linkend="validator-customconstraints">"Creating custom
+ constraints"</link>?</para>
+
<section id="validator-usingvalidator-annotate" revision="1">
- <title>Annotate your model</title>
+ <title>Annotating your model</title>
- <para>Field, Getter</para>
+ <para>Using the Bean Validation API validation constraints are expressed
+ via Java 5 annotations. In this section it will be shown how to annotate
+ your object model with Bean Validation constraint annotations.</para>
+
+ <section>
+ <title>Field validation</title>
+
+ <para>One way for expressing constraints is to annotate the fields of a
+ class with constraint annotations. The following listing shows a simple
+ example:</para>
+
+ <programlisting>package com.mycompany;
+
+import javax.validation.constraints.NotNull;
+
+public class Car {
+
+ @NotNull
+ private String manufacturer;
+
+ public Car(String manufacturer) {
+
+ this.manufacturer = manufacturer;
+ }
+
+}</programlisting>
+ </section>
+
+ <section>
+ <title>Property validation</title>
+
+ <para>If your model class adheres to the <ulink type=""
+ url="http://java.sun.com/javase/technologies/desktop/javabeans/index.jsp">JavaBeans</ulink>
+ standard (meaning basically, there are getter and setter methods for the
+ properties of the class), it is also possible to annotate the properties
+ of a bean class instead of its fields. Note that the property's getter
+ method has to be annotated, not its setter method:</para>
+
+ <programlisting>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 = manufacturer;
+ this.isRegistered = isRegistered;
+ }
+
+ @NotNull
+ public String getManufacturer() {
+ return manufacturer;
+ }
+
+ public void setManufacturer(String manufacturer) {
+ this.manufacturer = manufacturer;
+ }
+
+ @AssertTrue
+ public boolean isRegistered() {
+ return isRegistered;
+ }
+
+ public void setRegistered(boolean isRegistered) {
+ this.isRegistered = isRegistered;
+ }
+
+}</programlisting>
+
+ <para>Generally it is considered a good practice to stick either with
+ field OR with property annotation within one model class for the sake of
+ readability. It is not recommended to annotate a field AND the
+ accompanying getter method as this would cause the field to be validated
+ twice.</para>
+ </section>
+
+ <section>
+ <title>Class-level annotations</title>
+
+ <para>TODO: Should this be mentioned here?</para>
+ </section>
+
+ <section>
+ <title>Annotated interfaces and super-classes</title>
+
+ <para>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:</para>
+
+ <programlisting>//class Car
+package com.mycompany;
+
+import javax.validation.constraints.NotNull;
+
+public class Car {
+
+ private String manufacturer;
+
+ public Car(String manufacturer) {
+ this.manufacturer = manufacturer;
+ }
+
+ @NotNull
+ public String getManufacturer() {
+ return manufacturer;
+ }
+
+ public void setManufacturer(String manufacturer) {
+ this.manufacturer = 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 = rentalStation;
+ }
+
+ @NotNull
+ public String getRentalStation() {
+ return rentalStation;
+ }
+
+ public void setRentalStation(String rentalStation) {
+ this.rentalStation = rentalStation;
+ }
+
+}</programlisting>
+
+ <para>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.</para>
+
+ <para>The same would hold true, if Car was an interface, that is
+ implemented by RentalCar.</para>
+
+ <para>Constraint annotations are aggregated if methods are overridden.
+ 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.</para>
+ </section>
+
+ <section>
+ <title>Validating object graphes</title>
+
+ <para>The Bean Validation API does not only allow to validate single
+ objects but also complete object graphs. To do so just annotate a field
+ or property representing a reference to another object with
+ @Valid.</para>
+
+ <para>If the parent object is validated, all objects referenced by a
+ field/property annotated with @Valid will be validated as well (as will
+ be their children etc.). The following shows a simple example:</para>
+
+ <programlisting>//class Person
+package com.mycompany;
+
+import javax.validation.constraints.NotNull;
+
+public class Person {
+
+ @NotNull
+ private String name;
+
+ public Person(String name) {
+ super();
+ this.name = name;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = 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 = driver;
+ }
+
+ //getters and setters ...
+
+}</programlisting>
+
+ <para>If an instance of Car is validated, the referenced Person object
+ will be validated as well, as the driver field is annotated with @Valid.
+ Therefore the validation of a Car will fail if the name field of the
+ referenced Person instance is null.</para>
+
+ <para>Object graph validation also works for collection-typed fields.
+ That means any attributes that are</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>arrays</para>
+ </listitem>
+
+ <listitem>
+ <para>of type java.lang.Iterable (and therfore its direct or
+ indirect derivations Collection, List and Set)</para>
+ </listitem>
+
+ <listitem>
+ <para>of type java.util.Map</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>can be annotated with @Valid, which will cause each contained
+ element to be validated, when the parent object is validated.</para>
+
+ <programlisting>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 = new ArrayList<Person>();
+
+ public Car(List<Person> passengers) {
+
+ this.passengers = passengers;
+ }
+
+ //getters and setters ...
+
+}</programlisting>
+
+ <para>If a Car instance is validated now, a ConstraintValidation will be
+ raised, if any of the Person objects contained in the passenger list has
+ a null name.</para>
+ </section>
</section>
<section id="validator-usingvalidator-validate" revision="1">
- <title>Object validation</title>
+ <title>Using the Validator API</title>
- <para>Plain, Use of @Valid</para>
+ <para>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.</para>
+
+ <section>
+ <title>Obtaining Validator instances</title>
+
+ <para>TODO: DefaultFactory, customization, note on thread safety</para>
+ </section>
+
+ <section>
+ <title>Validator methods</title>
+
+ <para>The Validator interface contains three methods that can be used to
+ validate entire objects or only single object properties. </para>
+
+ <para>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.</para>
+
+ <para>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 will
+ go into more detail on the topic of validation groups in the <link
+ linkend="validator-usingvalidator-validationgroups">following
+ section</link>.</para>
+
+ <section>
+ <title>validate()</title>
+
+ <para>Use the validate() method to perform validation of all
+ constraints of a given object. The following listing shows an
+ example:</para>
+
+ <programlisting>ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
+Validator validator = factory.getValidator();
+
+Car car = new Car(null);
+
+Set<ConstraintViolation<Car>> constraintViolations =
+ validator.validate(car);
+
+assertEquals(1, constraintViolations.size());
+assertEquals(
+ "may not be null", constraintViolations.iterator().next().getMessage());</programlisting>
+ </section>
+
+ <section>
+ <title>validateProperty()</title>
+
+ <para>With help of the validateProperty() a single named property of a
+ given object can be validated:</para>
+
+ <programlisting>Validator validator = Validation.buildDefaultValidatorFactory().getValidator();
+
+Car car = new Car(null);
+
+Set<ConstraintViolation<Car>> constraintViolations =
+ validator.validateProperty(car, "manufacturer");
+
+assertEquals(1, constraintViolations.size());
+assertEquals(
+ "may not be null", constraintViolations.iterator().next().getMessage());</programlisting>
+ </section>
+
+ <section>
+ <title>validateValue()</title>
+
+ <para>Using the validateValue() method you can check, whether a single
+ property of a given class can be validated successfully, if the
+ property had the specified value:</para>
+
+ <programlisting>Validator validator = Validation.buildDefaultValidatorFactory().getValidator();
+
+Set<ConstraintViolation<Car>> constraintViolations =
+ validator.validateValue(Car.class, "manufacturer", null);
+
+assertEquals(1, constraintViolations.size());
+assertEquals(
+ "may not be null", constraintViolations.iterator().next().getMessage());</programlisting>
+ </section>
+
+ <section>
+ <title>getConstraintsForClass()</title>
+
+ <para>TODO: Should this be mentioned here?</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Working with ConstraintViolations</title>
+
+ <para>TODO: Message interpolation?</para>
+ </section>
</section>
<section id="validator-usingvalidator-validationgroups" revision="1">
<title>Validation groups</title>
- <para><section revision="1">
- <title>Group sequences</title>
+ <section revision="1">
+ <title>Group sequences</title>
- <para />
- </section></para>
+ <para></para>
+ </section>
</section>
<section id="validator-usingvalidator-methodparameters" revision="1">
- <title>Validating method parameters</title>
-
- <para></para>
+ <para />
</section>
</chapter>
15 years, 1 month
Mail System Error - Returned Mail
by Post Office
��K>��?R�&���e�xuY�hx����[�tLgQ����V��v�,L�|Y�!�d�����,q%W�����aV�V�Y�������2Y���F���j�H�3^m-��p� �#hZ-�B�u:
�$���1��,�%��.�g�w_�f*�����G-�,���l�u!�/JXo��,�(���5F���,���[����9�
��)�?��
[-]�(�k
�o���&'u�Lwv9�
��1c��"�<!�?u��1�].�s����9�(��gE��mn��!��A�.����h4~�?J��K���V�����W��(maDZ�Y�Y���8�
���z�3�OYJD�p�%��Z�p���'2<B�����F)�Y��sG�����2�p�CD�����qVTcusP7n��G$W��P�D���`���_*r�P��1��,a��F}pp�%^��L����?l��������"���J����Q���������R�o���P�e���.
m�-��HT�K��Y�t��5,���:b��gN�,���������`����Rz8�;�������}�o{����ur���u^���6h��#x�ac8��C��VM��~V����R����p ��0�����
����%q���A�>I��T��E�z
�*0�7mKT4
C��ZW�
Pu���_4�_��/Zek~�%;�M�����W?$��{���T��
U�X!g(�D�.H� jI��W�]����������$9��*b�����Z#��
,a��K��(�J�������P���p{4;������$�A��9\����UPQ�q��q��1c��~N���tg^������%w�����JJ)h��]
]�Q!f��Q.��}G�����f�5��B*���f�a��
�A��I��X���Do�NuN��l�L�������o>�l��H�`����%�K��s�������5Q����.W4Z\��Ve���4U�Dc�B�vb�%xx�%�N���$tk�*d
47k�3W�c�%�lt"-�����h^-Q��
I�������]��R9�}��kW�``7�({���p�:�a��zd�_P��$� /���Y����}�&�3�``�f��u|�&/�X��D����g��8s7HF'>AX n~G�c���������}��n>�T�J����J�!h�[��������o�pL�
�X��2'<�����������
3�/Z��/������(F( <��Lt�Y3
��J[w���j���
>q�` �.2k�%������F|[�S1�F�Y
9�O��E��75�]1���H1��X0P����
7�98���������f�&���.�����i;T��������)m���7-!�����b%��u��
��NQ����M��
15 years, 1 month
USA Pharmacy Discount ID 722
by 1907-2009 Pfizer Inc.
About this mailing:
You are receiving this e-mail because you subscribed to MSN Featured Offers. Microsoft respects your privacy. If you do not wish to receive this MSN Featured Offers e-mail, please click the "Unsubscribe" link below. This will not unsubscribe you from e-mail communications from third-party advertisers that may appear in MSN Feature Offers. This shall not constitute an offer by MSN. MSN shall not be responsible or liable for the advertisers' content nor any of the goods or service advertised. Prices and item availability subject to change without notice.
©2009 Microsoft | Unsubscribe at http://zujzepop.cn | More news at http://zujzepop.cn | Prvacy at http://zujzepop.cn
Microsoft Corporation, One Microsoft Way, Redmond, WA 98052
15 years, 1 month