[hibernate-commits] Hibernate SVN: r16243 - in validator/trunk/hibernate-validator/src/main/docbook/en-US: modules and 1 other directory.

Author: hardy.ferentschik Date: 2009-03-31 09:26:27 -0400 (Tue, 31 Mar 2009) New Revision: 16243 Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml Log: minor changes and style changes Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml =================================================================== --- validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml 2009-03-31 12:28:53 UTC (rev 16242) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml 2009-03-31 13:26:27 UTC (rev 16243) @@ -65,37 +65,12 @@ <preface> <title>Preface Alpha Release</title> - <para>This release has alpha status, meaning that neither the - implementation nor this documenation is complete. However, implementation - should be in a state allowing first experiments with this new API. The - following list shows the missing features in relation to the <ulink - url="http://in.relation.to/service/File/10924">1.0.CR1 version of JSR - 303</ulink> :</para> + <para>This release has alpha status, which means that neither the + implementation nor this documenation is complete. You can find more + information about the current state of the implementation on the <ulink + url="http://www.hibernate.org/459.html">Bean Validation Roadmap</ulink> or + you can refer to JSR 303 directly for further examples.</para> - <itemizedlist> - <listitem> - <para>Implicit grouping</para> - </listitem> - - <listitem> - <para>Implementation of the <classname>TraversableResolver</classname> - interface to allow integration with JPA</para> - </listitem> - - <listitem> - <para>XML configuration</para> - </listitem> - </itemizedlist> - - <para>You can find more information about the current state of the - implementation on the <ulink url="http://www.hibernate.org/459.html">Bean - Validation Roadmap</ulink>.</para> - - <para>The documentation contains so far only a "Getting started" section. - Work is in progress in this area and following releases will have more up - to date documentation. For now refer to JSR 303 directly for further - examples.</para> - <para>Please report any problems or bugs in either <ulink url="http://opensource.atlassian.com/projects/hibernate/browse/HV&qu... Hibernate Validator</ulink> or on the <ulink @@ -129,13 +104,16 @@ <!--xi:include href="modules/introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /--> - <xi:include href="modules/gettingstarted.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="modules/gettingstarted.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- - <xi:include href="modules/usingvalidator.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> ---> - <xi:include href="modules/customconstraints.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -<!-- + <xi:include href="modules/usingvalidator.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="modules/customconstraints.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <!-- <xi:include href="modules/xmlconfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="modules/integration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="modules/extendedri.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> 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-31 12:28:53 UTC (rev 16242) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml 2009-03-31 13:26:27 UTC (rev 16243) @@ -25,20 +25,22 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="validator-customconstraints"> - <title>Creating custom constraints</title> + <title>Custom constraints</title> <para>Though the Bean Validation API defines a whole bunch of standard - constraint annotations such as @NotNull, @Size, @Min or @AssertTrue, one can - easily think of situations, for which these standard annotations won't - suffice. But as the specification was designed with extensibility in mind, - you are able to create custom constraints tailored to your specific - validation requirements in a simple and timely manner.</para> + constraint annotations such as <classname>@NotNull</classname>, + <classname>@Size</classname>, <classname>@Min</classname> or + <classname>@AssertTrue</classname>, one can easily think of situations, for + which these standard annotations won't suffice. But as the specification was + designed with extensibility in mind, you are able to create custom + constraints tailored to your specific validation requirements in a simple + and timely manner.</para> <section id="validator-customconstraints-simple" revision="1"> <title>Creating a simple constraint</title> <para>To create a custom constraint, the following three steps are - required, which will be explained in the following:</para> + required:</para> <itemizedlist> <listitem> @@ -60,23 +62,21 @@ <title>Creating a constraint annotation</title> <para>Let's write a constraint annotation, that can be used to express - 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 <link linkend="validator-gettingstarted">Getting - started</link> chapter is always an upper-case String.</para> + that a given string shall either be upper case or lower case. We'll + apply it later on to ensure, that the <property>licensePlate</property> + field of the <classname>Car</classname> class from the <link + linkend="validator-gettingstarted">Getting started</link> chapter is + always an upper-case string.</para> <para>First we need a way to express the two case modes. We might use - String constants, but a better way to go is to use a Java 5 enum for - that purpose:</para> + <classname>String</classname> constants, but a better way to go is to + use a Java 5 enum for that purpose:</para> <programlisting>package com.mycompany; public enum CaseMode { - UPPER, - LOWER; - }</programlisting> <para>Now we can define the actual constraint annotation. If you've @@ -108,10 +108,10 @@ }</programlisting> - <para>An annotation type is defined using the @interface keyword. All - attributes of an annotation type are declared in a method-like manner. - The specification of the Bean Validation API demands, that any - constraint annotation defines</para> + <para>An annotation type is defined using the <code>@interface</code> + keyword. All attributes of an annotation type are declared in a + method-like manner. The specification of the Bean Validation API + demands, that any constraint annotation defines</para> <itemizedlist> <listitem> @@ -121,9 +121,10 @@ <listitem> <para>an attribute "groups" that allows the specification of - validation groups, to which this constraint belongs (see section - "Using validation groups" for further details, TODO GM: link). This - must default to an empty array of type Class&lt;?&gt;.</para> + validation groups, to which this constraint belongs (see <xref + linkend="validator-usingvalidator-validationgroups" />). This must + default to an empty array of type + <classname>Class&lt;?&gt;</classname>.</para> </listitem> </itemizedlist> @@ -131,32 +132,34 @@ for the required case mode to be specified. The name "value" is a special one, which can be omitted upon using the annotation, if it is the only attribute specified, as e.g. in - @CheckCase(CaseMode.UPPER).</para> + <code&gt;(a)CheckCase(CaseMode.UPPER)&lt;/code&gt;.&lt;/para&gt; <para>In addition we annotate the annotation type with a couple of so-called meta annotations:</para> <itemizedlist> <listitem> - <para>@Target({ METHOD, FIELD, ANNOTATION_TYPE }): Says, that - methods, fields and annotation declarations may be annotated with - @CheckCase (but not type declarations e.g.)</para> + <para><code>@Target({ METHOD, FIELD, ANNOTATION_TYPE })</code>: + Says, that methods, fields and annotation declarations may be + annotated with @CheckCase (but not type declarations e.g.)</para> </listitem> <listitem> - <para>@Retention(RUNTIME): Specifies, that annotations of this type - will be available at runtime by the means of reflection</para> + <para><code>@Retention(RUNTIME)</code>: Specifies, that annotations + of this type will be available at runtime by the means of + reflection</para> </listitem> <listitem> - <para>@Constraint(validatedBy = CheckCaseValidator.class): Specifies - the validator to be used to validate elements annotated with - @CheckCase</para> + <para><code>@Constraint(validatedBy = + CheckCaseValidator.class)</code>: Specifies the validator to be used + to validate elements annotated with @CheckCase</para> </listitem> <listitem> - <para>@Documented: Says, that the use of @CheckCase will be - contained in the JavaDoc of elements annotated with it</para> + <para><code>@Documented</code>: Says, that the use of + <code>@CheckCase</code> will be contained in the JavaDoc of elements + annotated with it</para> </listitem> </itemizedlist> </section> @@ -165,8 +168,9 @@ <title>Implementing the constraint validator</title> <para>Next, we need to implement a constraint validator, that's able to - validate elements with a @CheckCase annotation. To do so, we implement - the interface ConstraintValidator as shown below:</para> + validate elements with a <classname>@CheckCase</classname> annotation. + To do so, we implement the interface ConstraintValidator as shown + below:</para> <programlisting>package com.mycompany; @@ -194,58 +198,63 @@ }</programlisting> - <para>The ConstraintValidator interface defines two type parameters, - which we set in our implementation. The first one specifies the - annotation type to be validated (in our example CheckCase), the second - one the type of elements, which the validator can handle (here - String).</para> + <para>The <classname>ConstraintValidator</classname> interface defines + two type parameters, which we set in our implementation. The first one + specifies the annotation type to be validated (in our example + CheckCase), the second one the type of elements, which the validator can + handle (here String).</para> <para>In case a constraint annotation is allowed at elements of - different types, a ConstraintValidator for each allowed type has to be - implemented and registered at the constraint annotation as shown - above.</para> + different types, a <classname>ConstraintValidator</classname> for each + allowed type has to be implemented and registered at the constraint + annotation as shown above.</para> <para>The implementation of the validator is straightforward. The - initialize() method gives us access to the attribute values of the - annotation to be validated. In the example we store the CaseMode in a - field of the validator for further usage.</para> + <methodname>initialize()</methodname> method gives us access to the + attribute values of the annotation to be validated. In the example we + store the CaseMode in a field of the validator for further usage.</para> - <para>In the isValid() method we implement the logic, that determines, - whether a String is valid according to a given @CheckCase annotation or - not. This decision depends on the case mode retrieved in initialize(). - As the Bean Validation specification recommends, we consider null values - as being valid. If null is not a valid value for an element, it should - be annotated with @NotNull explicitely.</para> + <para>In the <methodname>isValid()</methodname> method we implement the + logic, that determines, whether a <classname>String</classname> is valid + according to a given <classname>@CheckCase</classname> annotation or + not. This decision depends on the case mode retrieved in + <classname>initialize()</classname>. As the Bean Validation + specification recommends, we consider <code>null</code> values as being + valid. If <code>null</code> is not a valid value for an element, it + should be annotated with <code>@NotNull</code> explicitely.</para> - <para>The passed-in ConstraintValidatorContext could be used to raise - any custom validation errors, but as we are fine with the default - behavior, we can ignore that parameter for now (TODO GM: example for - usage).</para> + <para>The passed-in <classname>ConstraintValidatorContext</classname> + could be used to raise any custom validation errors, but as we are fine + with the default behavior, we can ignore that parameter for now (TODO + GM: example for usage).</para> </section> <section id="validator-customconstraints-errormessage" revision="1"> <title>Defining the error message</title> <para>Finally we need to specify the error message, that shall be used, - in case a @CheckCase constraint is violated. To do so, we create a file - named ValidationMessages.properties under src/main/resources with the - following content:</para> + in case a <classname>@CheckCase</classname> constraint is violated. To + do so, we create a file named + <filename>ValidationMessages.properties</filename> under + <filename>src/main/resources</filename> with the following + content:</para> <programlisting>validator.checkcase=Case mode must be {value}.</programlisting> <para>If a validation error occurs, the validation runtime will use the default value, that we specified for the message attribute of the - @CheckCase annotation to look up the error message in this file.</para> + <classname>@CheckCase</classname> annotation to look up the error + message in this file.</para> </section> <section id="validator-customconstraints-using" revision="1"> <title>Using the constraint</title> <para>Now that our first custom constraint is completed, we can use it - in the Car class from the <link + in the <classname>Car</classname> class from the <link linkend="validator-gettingstarted">Getting started</link> chapter to - specify that the licensePlate field shall only contain upper-case - Strings:</para> + specify that the <property>licensePlate</property> field shall only + contain upper-case strings:</para> <programlisting>package com.mycompany; @@ -277,8 +286,9 @@ }</programlisting> - <para>Finally let's demonstrate in a little test that the @CheckCase - constraint is properly validated:</para> + <para>Finally let's demonstrate in a little test that the + <classname>@CheckCase</classname> constraint is properly + validated:</para> <programlisting>package com.mycompany; @@ -334,16 +344,19 @@ <section id="validator-customconstraints-compound" revision="1"> <title>Constraint composition</title> - <para>Looking at the licensePlate field of the Car class, we see three - constraint annotations already. In complexer scenarios, where even more - constraints could be applied to one element, this might become a bit - confusing easily. Furthermore, if we had a licensePlate field in another - class, we would have to copy all constraint declarations to the other - class as well, violating the DRY principle.</para> + <para>Looking at the <property>licensePlate</property> field of the + <classname>Car</classname> class, we see three constraint annotations + already. In complexer scenarios, where even more constraints could be + applied to one element, this might become a bit confusing easily. + Furthermore, if we had a <property>licensePlate</property> field in + another class, we would have to copy all constraint declarations to the + other class as well, violating the DRY principle.</para> <para>This problem can be tackled using compound constraints. In the - following we create a new constraint annotation @ValidLicensePlate, that - comprises the constraints @NotNull, @Size and @CheckCase:</para> + following we create a new constraint annotation + <classname>@ValidLicensePlate</classname>, that comprises the constraints + <classname>@NotNull</classname>, <classname>@Size</classname> and + <classname>@CheckCase</classname>:</para> <programlisting>package com.mycompany; @@ -375,15 +388,18 @@ <para>To do so, we just have to annotate the constraint declaration with its comprising constraints (btw. that's exactly why we allowed annotation - types as target for the @CheckCase annotation). As no additional - validation is required for the @ValidLicensePlate annotation itself, we - don't declare a validator within the @Constraint meta annotation.</para> + types as target for the <classname>@CheckCase</classname> annotation). As + no additional validation is required for the + <classname>@ValidLicensePlate</classname> annotation itself, we don't + declare a validator within the <classname>@Constraint </classname>meta + annotation.</para> <para>TODO GM: Specifying no validator does not yet work.</para> - <para>Using the new compound constraint at the licensePlate field now is - fully equivalent to the previous version, where we declared the three - constraints directly at the field itself:</para> + <para>Using the new compound constraint at the + <property>licensePlate</property> field now is fully equivalent to the + previous version, where we declared the three constraints directly at the + field itself:</para> <programlisting>package com.mycompany; @@ -396,12 +412,14 @@ }</programlisting> - <para>The set of ConstraintViolations retrieved when validating a Car - instance will contain an entry for each violated composing constraint of - the @ValidLicensePlate constraint. If you rather prefer a single - ConstraintViolation in case any of the composing constraints is violated, - the @ReportAsSingleViolation meta constraint can be used as - follows:</para> + <para>The set of <classname>ConstraintViolations</classname> retrieved + when validating a <classname>Car</classname> instance will contain an + entry for each violated composing constraint of the + <classname>@ValidLicensePlate</classname> constraint. If you rather prefer + a single <classname>ConstraintViolation</classname> in case any of the + composing constraints is violated, the + <classname>@ReportAsSingleViolation</classname> meta constraint can be + used as follows:</para> <programlisting>//... @ReportAsSingleViolation Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml =================================================================== --- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml 2009-03-31 12:28:53 UTC (rev 16242) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml 2009-03-31 13:26:27 UTC (rev 16243) @@ -26,7 +26,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="validator-gettingstarted"> - <title id="getting-started">Getting started in 5 minutes</title> + <title id="getting-started">Getting started</title> <para>This chapter will show you how to quickly get started with the reference implementation (RI) of the Bean Validation API as specified by JSR @@ -104,9 +104,11 @@ <para>Finally confirm all entered values and change into the newly created project directory. All properties of a Maven project (such as its dependencies to other libraries, the steps to be performed during build - etc.) are described in a file called pom.xml (project object model), - located in the project's root directory. Now open the project's pom.xml - and perform the following changes:</para> + etc.) are described in a file called pom.xml (<emphasis + role="bold">p</emphasis>roject <emphasis role="bold">o</emphasis>bject + <emphasis role="bold">m</emphasis>odel), located in the project's root + directory. Now open the project's pom.xml and perform the following + changes:</para> <itemizedlist> <listitem> @@ -178,7 +180,7 @@ <title>Applying constraints to a model class</title> <para>Having set up the project, it's time now to actually make use of the - Bean Validation API. Therefore, open the project in the IDE of you choice + Bean Validation API. Therefore, 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 <ulink url="http://m2eclipse.codehaus.org/">M2Eclipse</ulink> plugin. NetBeans @@ -215,28 +217,29 @@ }</programlisting></para> - <para>@NotNull, @Size and @Min are so-called constraint annotions, that we - use to declare certain constraints, which shall be applied to the fields - of a Car instance:</para> + <para><classname>@NotNull</classname>, <classname>@Size</classname> and + <classname>@Min</classname> are so-called constraint annotions, that we + use to declare constraints, which shall be applied to the fields of a + <classname>Car</classname> instance:</para> <itemizedlist> <listitem> - <para>manufacturer shall never be null</para> + <para><property>manufacturer</property> shall never be null</para> </listitem> <listitem> - <para>licensePlate shall never be null and must be between 2 and 14 - characters long</para> + <para><property>licensePlate</property> shall never be null and must + be between 2 and 14 characters long</para> </listitem> <listitem> - <para>seatCount shall be at least 2.</para> + <para><property>seatCount</property> shall be at least 2.</para> </listitem> </itemizedlist> - <para>To perform a validation of these constraints, we use the Validator - interface defined by the specification. Let's try it in a test for our Car - class:</para> + <para>To perform a validation of these constraints, we use the + <classname>Validator</classname> interface defined by the specification. + Let's try it in a test for our <classname>Car</classname> class:</para> <para><programlisting>package com.mycompany; @@ -313,41 +316,45 @@ } }</programlisting></para> - <para>In the setUp() method we get a Validator object from the - ValidatorFactory. A Validator instance is thread-safe and may be reused + <para>In the <methodname>setUp()</methodname> method we get a + <classname>Validator</classname> object from the + <classname>ValidatorFactory</classname>. A + <classname>Validator</classname> instance is thread-safe and may be reused multiple times, therefore we store it as field of our test class. We can use the validator now to validate the different car objects in the test methods.</para> - <para>The validate() method returns a set of ConstraintViolation objects, - which we can iterate through in order to see which validation errors - occured. The first three test methods show some expected constraint - violations:</para> + <para>The <methodname>validate()</methodname> method returns a set of + <classname>ConstraintViolation</classname> objects, which we can iterate + through in order to see which validation errors occured. The first three + test methods show some expected constraint violations:</para> <itemizedlist> <listitem> - <para>The @NotNull constraint on manufacturer is violated in - manufacturerIsNull()</para> + <para>The <classname>@NotNull</classname> constraint on manufacturer + is violated in <methodname>manufacturerIsNull()</methodname></para> </listitem> <listitem> - <para>The @Size constraint on licensePlate is violated in - licensePlateTooShort()</para> + <para>The <classname>@Size</classname> constraint on licensePlate is + violated in <methodname>licensePlateTooShort()</methodname></para> </listitem> <listitem> - <para>The @Min constraint on seatCount is violated in - seatCountTooLow()</para> + <para>The <classname>@Min</classname> constraint on seatCount is + violated in <methodname>seatCountTooLow()</methodname></para> </listitem> </itemizedlist> - <para>If the object could be validated successfully (as in carIsValid()), - validate() returns an empty set.</para> + <para>If the object could be validated successfully (as in + <methodname>carIsValid()</methodname>), + <methodname>validate()</methodname> returns an empty set.</para> - <para>Note that we only use classes from the package javax.validation, - which stems from the Bean Validation 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, should that need arise.</para> + <para>Note that we only use classes from the package + <package>javax.validation</package>, which stems from the Bean Validation + 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, should + that need arise.</para> </section> <section id="validator-gettingstarted-whatsnext" revision="1"> 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-31 12:28:53 UTC (rev 16242) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml 2009-03-31 13:26:27 UTC (rev 16243) @@ -25,7 +25,7 @@ <!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>Object validation using the Bean Validation API</title> + <title>Object validation</title> <para>TODO: outline of the chapter. Should this be placed before <link lang="" linkend="validator-customconstraints">"Creating custom @@ -35,11 +35,11 @@ <title>Annotating your model</title> <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> + via Java 5 annotations. In this section we show how to annotate your + object model with Bean Validation constraint annotations.</para> <section> - <title>Field validation</title> + <title>Field level annotations</title> <para>One way for expressing constraints is to annotate the fields of a class with constraint annotations. The following listing shows a simple @@ -51,19 +51,18 @@ public class Car { - @NotNull + <emphasis role="bold">@NotNull</emphasis> private String manufacturer; public Car(String manufacturer) { this.manufacturer = manufacturer; } - }</programlisting> </section> <section> - <title>Property validation</title> + <title>Property level annotations</title> <para>If your model class adheres to the <ulink type="" url="http://java.sun.com/javase/technologies/desktop/javabeans/index... @@ -90,7 +89,7 @@ this.isRegistered = isRegistered; } - @NotNull + <emphasis role="bold">@NotNull</emphasis> public String getManufacturer() { return manufacturer; } @@ -99,7 +98,7 @@ this.manufacturer = manufacturer; } - @AssertTrue + <emphasis role="bold">@AssertTrue</emphasis> public boolean isRegistered() { return isRegistered; } @@ -107,30 +106,34 @@ 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> + field <emphasis>or</emphasis> with property annotation within one model + class for the sake of readability. It is not recommended to annotate a + field <emphasis>and</emphasis> the accompanying getter method as this + would cause the field to be validated twice.</para> + + <para>TODO: Make it explcit that where the difference lies between filed + and property level annotations. Depending where I place the annotation + the value to be validated gets accessed in different ways!</para> </section> <section> <title>Class-level annotations</title> - <para>TODO: Should this be mentioned here?</para> + <para>TODO: Should this be mentioned here? Yes it should :) + (hardy)</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> + <para>When validating an object that implements an interface or extends + another class, all constraint annotations on the implemented interface + and parent class apply in the same manner as the constraints specified + on the validated object itself. To make things clearer let's have a look + at the following example:</para> <programlisting>//class Car package com.mycompany; @@ -181,33 +184,38 @@ }</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>Our well-known class <classname>Car</classname> is now extended by + <classname>RentalCar</classname> with an additional property, + <property>rentalStation</property>. If an instance of + <classname>RentalCar</classname> is validated now, not only the + <classname>@NotNull</classname> constraint at the + <property>rentalStation</property> property would be validated, but also + the constraint at <property>manufacturer</property> from the parent + class.</para> - <para>The same would hold true, if Car was an interface, that is - implemented by RentalCar.</para> + <para>The same would hold true, if <classname>Car</classname> was an + interface, that is implemented by + <classname>RentalCar</classname>.</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> + If <classname>RentalCar</classname> would override the + <methodname>getManufacturer()</methodname> method from + <classname>Car</classname> any constraints annotated at the overriding + method would be evaluated in addition to the + <classname>@NotNull</classname> constraint from the super-class.</para> </section> <section> - <title>Validating object graphes</title> + <title>Validating object graphs</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> + <classname>@Valid</classname>. If the parent object is validated, all + objects referenced by a field/property annotated with + <classname>@Valid</classname> will be validated as well (as will be + their children etc.). The following shows a simple example:</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; @@ -254,10 +262,13 @@ }</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>If an instance of <classname>Car</classname> is validated, the + referenced <classname>Person</classname> object will be validated as + well, as the <property>driver</property> field is annotated with + <classname>@Valid</classname>. Therefore the validation of a + <classname>Car</classname> will fail if the <property>name</property> + field of the referenced <classname>Person</classname> instance is + <code>null</code>.</para> <para>Object graph validation also works for collection-typed fields. That means any attributes that are</para> @@ -268,17 +279,20 @@ </listitem> <listitem> - <para>of type java.lang.Iterable (and therfore its direct or - indirect derivations Collection, List and Set)</para> + <para>of type<classname> java.lang.Iterable</classname> (and + therfore its direct or indirect derivations + <classname>Collection</classname>, <classname>List</classname> and + <classname>Set</classname>)</para> </listitem> <listitem> - <para>of type java.util.Map</para> + <para>of type <classname>java.util.Map</classname></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> + <para>can be annotated with <classname>@Valid</classname>, which will + cause each contained element to be validated, when the parent object is + validated.</para> <programlisting>package com.mycompany; @@ -307,21 +321,24 @@ }</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> + <para>If a <classname>Car</classname> instance is validated now, a + <classname>ConstraintValidation</classname> will be raised, if any of + the <classname>Person</classname> objects contained in the + <property>passengers</property> list has a <code>null</code> + name.</para> </section> </section> <section id="validator-usingvalidator-validate" revision="1"> - <title>Using the Validator API</title> + <title>Validating your model</title> - <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> + <para>The <classname>Validator</classname> interface is the main entry + point to the Bean Validation API. In the following we first will show how + to obtain <classname>Validator</classname> instances using the + bootstrapping mechanism that the API provides. Afterwards you'll learn how + to use the different methods of the <classname>Validator</classname> + interfaces followed by an overview of the information that + <classname>ConstraintViolation</classname> instances offer.</para> <section> <title>Obtaining Validator instances</title> @@ -332,13 +349,15 @@ <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>The <classname>Validator</classname> 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&lt;ConstraintViolation&gt;, - which will be empty, if the validation succeeded. Otherwise a - ConstraintViolation object for each violated constraint will be - contained.</para> + <para>All of these methods return a + <classname>Set&lt;ConstraintViolation&gt;</classname>, which will be + empty, if the validation succeeded. Otherwise a + <classname>ConstraintViolation</classname> 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 @@ -351,9 +370,9 @@ <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> + <para>Use the <methodname>validate()</methodname> 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(); @@ -371,8 +390,8 @@ <section> <title>validateProperty()</title> - <para>With help of the validateProperty() a single named property of a - given object can be validated:</para> + <para>With help of the <methodname>validateProperty()</methodname> a + single named property of a given object can be validated:</para> <programlisting>Validator validator = Validation.buildDefaultValidatorFactory().getValidator(); @@ -389,9 +408,9 @@ <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> + <para>Using the <methodname>validateValue() </methodname>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(); @@ -406,7 +425,7 @@ <section> <title>getConstraintsForClass()</title> - <para>TODO: Should this be mentioned here?</para> + <para>TODO: Should this be mentioned here? Yes! (HF)</para> </section> </section>