From hibernate-commits at lists.jboss.org Tue Mar 31 09:26:28 2009
Content-Type: multipart/mixed; boundary="===============0450483037925117161=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r16243 - in
 validator/trunk/hibernate-validator/src/main/docbook/en-US: modules and 1
 other directory.
Date: Tue, 31 Mar 2009 09:26:27 -0400
Message-ID: <E1Lodz1-0003iU-TH@committer01.frg.pub.inap.atl.jboss.com>

--===============0450483037925117161==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

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/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:
minor changes and style changes

Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/master=
.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/master.xml	2=
009-03-31 12:28:53 UTC (rev 16242)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml	2=
009-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, implementat=
ion
-    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=3D"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=3D"http://www.hibernate.org/459.html">Bean Validation Roadmap</uli=
nk> 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</classn=
ame>
-        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=3D"http://www.hibernate.org/459.html"=
>Bean
-    Validation Roadmap</ulink>.</para>
-
-    <para>The documentation contains so far only a "Getting started" secti=
on.
-    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=3D"http://opensource.atlassian.com/projects/hibernate/browse/HV">J=
ira
     Hibernate Validator</ulink> or on the <ulink
@@ -129,13 +104,16 @@
 =

   <!--xi:include href=3D"modules/introduction.xml" xmlns:xi=3D"http://www.=
w3.org/2001/XInclude" /-->
 =

-  <xi:include href=3D"modules/gettingstarted.xml" xmlns:xi=3D"http://www.w=
3.org/2001/XInclude" />
+  <xi:include href=3D"modules/gettingstarted.xml"
+              xmlns:xi=3D"http://www.w3.org/2001/XInclude" />
 =

-  <!--  =

-  <xi:include href=3D"modules/usingvalidator.xml" xmlns:xi=3D"http://www.w=
3.org/2001/XInclude" />	=

--->
-  <xi:include href=3D"modules/customconstraints.xml" xmlns:xi=3D"http://ww=
w.w3.org/2001/XInclude" />
-<!--
+  <xi:include href=3D"modules/usingvalidator.xml"
+              xmlns:xi=3D"http://www.w3.org/2001/XInclude" />
+
+  <xi:include href=3D"modules/customconstraints.xml"
+              xmlns:xi=3D"http://www.w3.org/2001/XInclude" />
+
+  <!--
   <xi:include href=3D"modules/xmlconfiguration.xml" xmlns:xi=3D"http://www=
.w3.org/2001/XInclude" />
   <xi:include href=3D"modules/integration.xml" xmlns:xi=3D"http://www.w3.o=
rg/2001/XInclude" />
   <xi:include href=3D"modules/extendedri.xml" xmlns:xi=3D"http://www.w3.or=
g/2001/XInclude" />

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-31 12:28:53 UTC (rev 16242)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/cust=
omconstraints.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=3D"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 min=
d,
-  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=3D"validator-customconstraints-simple" revision=3D"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 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 <link linkend=3D"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</proper=
ty>
+      field of the <classname>Car</classname> class from the <link
+      linkend=3D"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 manne=
r.
-      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). T=
his
-          must default to an empty array of type Class&lt;?&gt;.</para>
+          validation groups, to which this constraint belongs (see <xref
+          linkend=3D"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>@CheckCase(CaseMode.UPPER)</code>.</para>
 =

       <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 t=
ype
-          will be available at runtime by the means of reflection</para>
+          <para><code>@Retention(RUNTIME)</code>: Specifies, that annotati=
ons
+          of this type will be available at runtime by the means of
+          reflection</para>
         </listitem>
 =

         <listitem>
-          <para>@Constraint(validatedBy =3D CheckCaseValidator.class): Spe=
cifies
-          the validator to be used to validate elements annotated with
-          @CheckCase</para>
+          <para><code>@Constraint(validatedBy =3D
+          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 elem=
ents
+          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 impleme=
nt
-      the interface ConstraintValidator as shown below:</para>
+      validate elements with a <classname>@CheckCase</classname> annotatio=
n.
+      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 seco=
nd
-      one the type of elements, which the validator can handle (here
-      String).</para>
+      <para>The <classname>ConstraintValidator</classname> interface defin=
es
+      two type parameters, which we set in our implementation. The first o=
ne
+      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 ea=
ch
+      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.</p=
ara>
 =

-      <para>In the isValid() method we implement the logic, that determine=
s,
-      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 va=
lues
-      as being valid. If null is not a valid value for an element, it shou=
ld
-      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 v=
alid
+      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 be=
ing
+      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 f=
ine
+      with the default behavior, we can ignore that parameter for now (TODO
+      GM: example for usage).</para>
     </section>
 =

     <section id=3D"validator-customconstraints-errormessage" revision=3D"1=
">
       <title>Defining the error message</title>
 =

       <para>Finally we need to specify the error message, that shall be us=
ed,
-      in case a @CheckCase constraint is violated. To do so, we create a f=
ile
-      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=3DCase mode must be {value}.</pr=
ogramlisting>
 =

       <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.</pa=
ra>
+      <classname>@CheckCase</classname> annotation to look up the error
+      message in this file.</para>
     </section>
 =

     <section id=3D"validator-customconstraints-using" revision=3D"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=3D"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=3D"validator-customconstraints-compound" revision=3D"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 anoth=
er
-    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, th=
at
-    comprises the constraints @NotNull, @Size and @CheckCase:</para>
+    following we create a new constraint annotation
+    <classname>@ValidLicensePlate</classname>, that comprises the constrai=
nts
+    <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 wi=
th
     its comprising constraints (btw. that's exactly why we allowed annotat=
ion
-    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.</par=
a>
+    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 violat=
ed,
-    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 pr=
efer
+    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/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-03-31 12:28:53 UTC (rev 16242)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gett=
ingstarted.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=3D"validator-gettingstarted">
-  <title id=3D"getting-started">Getting started in 5 minutes</title>
+  <title id=3D"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 cre=
ated
     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=3D"bold">p</emphasis>roject <emphasis role=3D"bold">o</emphasis>b=
ject
+    <emphasis role=3D"bold">m</emphasis>odel), located in the project's ro=
ot
+    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 cho=
ice
+    Bean Validation API. Therefore, open the project in the IDE of your ch=
oice
     (for Eclipse, you may type mvn eclipse:eclipse to create a standard
     Eclipse project configuration OR you may use the <ulink
     url=3D"http://m2eclipse.codehaus.org/">M2Eclipse</ulink> plugin. NetBe=
ans
@@ -215,28 +217,29 @@
 =

 }</programlisting></para>
 =

-    <para>@NotNull, @Size and @Min are so-called constraint annotions, tha=
t we
-    use to declare certain constraints, which shall be applied to the fiel=
ds
-    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 mu=
st
+        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 Validat=
or
-    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 specificatio=
n.
+    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 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
     methods.</para>
 =

-    <para>The validate() method returns a set of ConstraintViolation objec=
ts,
-    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 itera=
te
+    through in order to see which validation errors occured. The first thr=
ee
+    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 manufactur=
er
+        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 referen=
ce
-    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 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.</para>
   </section>
 =

   <section id=3D"validator-gettingstarted-whatsnext" revision=3D"1">

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-31 12:28:53 UTC (rev 16242)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usin=
gvalidator.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=3D"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=3D"" linkend=3D"validator-customconstraints">"Creating custom
@@ -35,11 +35,11 @@
     <title>Annotating your model</title>
 =

     <para>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.</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 o=
f a
       class with constraint annotations. The following listing shows a sim=
ple
@@ -51,19 +51,18 @@
 =

 public class Car {
 =

-    @NotNull
+    <emphasis role=3D"bold">@NotNull</emphasis>
     private String manufacturer;
 =

     public Car(String manufacturer) {
 =

         this.manufacturer =3D manufacturer;
     }
-
 }</programlisting>
     </section>
 =

     <section>
-      <title>Property validation</title>
+      <title>Property level annotations</title>
 =

       <para>If your model class adheres to the <ulink type=3D""
       url=3D"http://java.sun.com/javase/technologies/desktop/javabeans/ind=
ex.jsp">JavaBeans</ulink>
@@ -90,7 +89,7 @@
         this.isRegistered =3D isRegistered;
     }
 =

-    @NotNull
+    <emphasis role=3D"bold">@NotNull</emphasis>
     public String getManufacturer() {
         return manufacturer;
     }
@@ -99,7 +98,7 @@
         this.manufacturer =3D manufacturer;
     }
 =

-    @AssertTrue
+    <emphasis role=3D"bold">@AssertTrue</emphasis>
     public boolean isRegistered() {
         return isRegistered;
     }
@@ -107,30 +106,34 @@
     public void setRegistered(boolean isRegistered) {
         this.isRegistered =3D 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 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.</para>
+      field <emphasis>or</emphasis> with property annotation within one mo=
del
+      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 f=
iled
+      and property level annotations. Depending where I place the annotati=
on
+      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 exte=
nds
+      another class, all constraint annotations on the implemented interfa=
ce
+      and parent class apply in the same manner as the constraints specifi=
ed
+      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 extende=
d 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 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.</para>
+      If <classname>RentalCar</classname> would override the
+      <methodname>getManufacturer()</methodname> method from
+      <classname>Car</classname> any constraints annotated at the overridi=
ng
+      method would be evaluated in addition to the
+      <classname>@NotNull</classname> constraint from the super-class.</pa=
ra>
     </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 fi=
eld
       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 w=
ill
-      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 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.</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> a=
nd
+          <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 wil=
l 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=3D"validator-usingvalidator-validate" revision=3D"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 use=
d 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 lis=
ting
+        shows an example:</para>
 =

         <programlisting>ValidatorFactory factory =3D Validation.buildDefau=
ltValidatorFactory();
 Validator validator =3D 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 =3D Validation.buildDefaultVal=
idatorFactory().getValidator();
 =

@@ -389,9 +408,9 @@
       <section>
         <title>validateValue()</title>
 =

-        <para>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:</para>
+        <para>Using the <methodname>validateValue() </methodname>method you
+        can check, whether a single property of a given class can be valid=
ated
+        successfully, if the property had the specified value:</para>
 =

         <programlisting>Validator validator =3D Validation.buildDefaultVal=
idatorFactory().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>
 =



--===============0450483037925117161==--