[hibernate-commits] Hibernate SVN: r17466 - validator/trunk/hibernate-validator/src/main/docbook/en-US/modules.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Wed Sep 2 09:14:22 EDT 2009
Author: hardy.ferentschik
Date: 2009-09-02 09:14:22 -0400 (Wed, 02 Sep 2009)
New Revision: 17466
Modified:
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/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:
HV-220
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-09-02 03:06:15 UTC (rev 17465)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml 2009-09-02 13:14:22 UTC (rev 17466)
@@ -64,9 +64,9 @@
<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 <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>
+ field of the <classname>Car</classname> class from <xref
+ linkend="validator-gettingstarted" /> is always an upper-case
+ string.</para>
<para>First we need a way to express the two case modes. We might use
<classname>String</classname> constants, but a better way to go is to
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-09-02 03:06:15 UTC (rev 17465)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml 2009-09-02 13:14:22 UTC (rev 17466)
@@ -29,25 +29,25 @@
<title id="getting-started">Getting started</title>
<para>This chapter will show you how to get started with Hibernate Validator
- - the reference implementation (RI) of the Bean Validation API. Be sure to
- fulfill the following prerequisites in order to proceed:</para>
+ - the reference implementation (RI) of Bean Validation. For the following
+ quickstart you need:</para>
<itemizedlist>
<listitem>
- <para>As the Bean Validation API expresses constraints by the means of
- annotations, Java version 5 or later must be installed</para>
+ <para>A JDK >= 5</para>
</listitem>
<listitem>
- <para>As <ulink url="http://maven.apache.org/">Apache Maven</ulink> will
- be used as build tool in the following, Maven must be installed and a
- functioning internet connection is required to allow Maven to download
- all dependent libraries</para>
+ <para><ulink url="http://maven.apache.org/">Apache Maven</ulink></para>
</listitem>
<listitem>
- <para>Once Maven is installed you should configure your remote
- repository by adding the following to your
+ <para>A functioning Internet connection (Maven has to download all
+ required libraries)</para>
+ </listitem>
+
+ <listitem>
+ <para>A properly configured remote repository. Add the following to your
<filename>settings.xml</filename>: <programlisting><repositories>
<repository>
<id>jboss</id>
@@ -81,9 +81,11 @@
<para>When presented with the list of available archetypes in the JBoss
Maven Repository select the
- <emphasis>hibernate-validator-quickstart-archetype </emphasis>and confirm
- the properties. Maven will create your project in the directory
- beanvalidation-gettingstarted. Change into this directory and run:</para>
+ <emphasis>hibernate-validator-quickstart-archetype. </emphasis>After
+ downloading all dependencies confirm the settings by just pressing enter.
+ Maven will create your project in the directory
+ <filename>beanvalidation-gettingstarted</filename>. Change into this
+ directory and run:</para>
<para><programlisting>mvn test</programlisting>You should see some
compiling and testing action taking place. Time to look at the actual
@@ -93,30 +95,35 @@
<section id="validator-gettingstarted-createmodel" revision="1">
<title>Applying constraints to a model class</title>
- <para>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
- has great Maven support too, as described <ulink
- url="http://wiki.netbeans.org/MavenBestPractices">here</ulink>) and open
- the class <classname>Car</classname>:</para>
+ <para>Open the project in the IDE of your choice and have a look at the
+ class <classname>Car</classname>:</para>
- <para><programlisting>package com.mycompany;
+ <note>
+ <para>Eclipse users can type mvn eclipse:eclipse to create a standard
+ Eclipse project configuration or they use the <ulink
+ url="http://m2eclipse.codehaus.org/">M2Eclipse</ulink> plugin. NetBeans
+ and Intellij have great built-in Maven support.</para>
+ </note>
+ <para><example xreflabel="Car-example">
+ <title>Class Car annotated with constraints</title>
+
+ <programlisting language="Java">package com.mycompany;
+
import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
public class Car {
- @NotNull
+ <emphasis role="bold">@NotNull</emphasis>
private String manufacturer;
- @NotNull
- @Size(min = 2, max = 14)
+ <emphasis role="bold">@NotNull</emphasis>
+ <emphasis role="bold">@Size(min = 2, max = 14)</emphasis>
private String licensePlate;
- @Min(2)
+ <emphasis role="bold">@Min(2)</emphasis>
private int seatCount;
public Car(String manufacturer, String licencePlate, int seatCount) {
@@ -127,12 +134,10 @@
}
//getters and setters ...
-
-}</programlisting></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
+}</programlisting>
+ </example><classname>@NotNull</classname>, <classname>@Size</classname>
+ and <classname>@Min</classname> are so-called constraint annotations, that
+ we use to declare constraints, which shall be applied to the fields of a
<classname>Car</classname> instance:</para>
<itemizedlist>
@@ -150,12 +155,15 @@
</listitem>
</itemizedlist>
- <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>To perform a validation of these constraints, we use a
+ <classname>Validator</classname> instance. Let's have a look at the
+ <classname>CarTest</classname> class:</para>
- <para><programlisting>package com.mycompany;
+ <example xreflabel="CarTest-example">
+ <title>Class CarTest showing validation examples</title>
+ <programlisting language="Java">package com.mycompany;
+
import static org.junit.Assert.*;
import java.util.Set;
@@ -187,8 +195,7 @@
validator.validate(car);
assertEquals(1, constraintViolations.size());
- assertEquals(
- "may not be null", constraintViolations.iterator().next().getMessage());
+ assertEquals("may not be null", constraintViolations.iterator().next().getMessage());
}
@Test
@@ -200,8 +207,7 @@
validator.validate(car);
assertEquals(1, constraintViolations.size());
- assertEquals(
- "size must be between 2 and 14", constraintViolations.iterator().next().getMessage());
+ assertEquals("size must be between 2 and 14", constraintViolations.iterator().next().getMessage());
}
@Test
@@ -213,8 +219,7 @@
validator.validate(car);
assertEquals(1, constraintViolations.size());
- assertEquals(
- "must be greater than or equal to 2", constraintViolations.iterator().next().getMessage());
+ assertEquals("must be greater than or equal to 2", constraintViolations.iterator().next().getMessage());
}
@Test
@@ -227,20 +232,21 @@
assertEquals(0, constraintViolations.size());
}
-}</programlisting></para>
+}</programlisting>
+ </example>
<para>In the <methodname>setUp()</methodname> method we get a
- <classname>Validator</classname> object from the
+ <classname>Validator</classname> instance 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
+ use the validator now to validate the different car instances in the test
methods.</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>
+ in order to see which validation errors occurred. The first three test
+ methods show some expected constraint violations:</para>
<itemizedlist>
<listitem>
@@ -259,21 +265,20 @@
</listitem>
</itemizedlist>
- <para>If the object could be validated successfully (as in
- <methodname>carIsValid()</methodname>),
+ <para>If the object could be validated successfully,
<methodname>validate()</methodname> returns an empty set.</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>
+ <package>javax.validation</package> from the Bean Validation API. As we
+ don't reference any classes of the RI directly, it would be no problem to
+ switch to another implementation of the API, should that need
+ arise.</para>
</section>
<section id="validator-gettingstarted-whatsnext" revision="1">
<title>Where to go next?</title>
<para>That concludes our 5 minute tour through the world of the Bean
- Validation RI. </para>
+ Validation RI.</para>
</section>
</chapter>
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-09-02 03:06:15 UTC (rev 17465)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml 2009-09-02 13:14:22 UTC (rev 17466)
@@ -25,16 +25,39 @@
<!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</title>
+ <title>Basic validation</title>
+ <para>In this chapter we will see in more detail how to use Bean Validation
+ to validate constraints for a given entity model. We will also learn which
+ default constraints the specification provides and which additional
+ constraints are only provided by Hibernate Validator. Let's start with how
+ to add constraints to an entity.</para>
+
<section id="validator-usingvalidator-annotate" revision="1">
<title>Annotating your model</title>
- <para>Using the Bean Validation API validation constraints are expressed
- via Java 5 annotations. In this section we show how to annotate your
- object model with Bean Validation constraint annotations.</para>
+ <para>Constraints in Bean Validation are expressed via Java annotations.
+ In this section we show how to annotate an object model with these
+ annotations. We have to differentiate between three different type of
+ constraint annotations - class-, field- and property-level
+ annotations.</para>
+ <para><note>
+ <para>Not all constraints can be placed on any of these levels. In
+ fact all the default constraints defined by Bean Validation cannot be
+ places at class level. The java.lang.annotation.Target annotation
+ placed on the constraint annotation itself determines on which
+ elements a constraint can be placed. See also </para>
+ </note></para>
+
<section>
+ <title id="validator-usingvalidator-classlevel">Class-level
+ annotations</title>
+
+ <para>TODO</para>
+ </section>
+
+ <section>
<title>Field level annotations</title>
<para>One way for expressing constraints is to annotate the fields of a
@@ -116,12 +139,6 @@
</section>
<section>
- <title>Class-level annotations</title>
-
- <para>TODO</para>
- </section>
-
- <section>
<title>Annotated interfaces and super-classes</title>
<para>When validating an object that implements an interface or extends
More information about the hibernate-commits
mailing list