Hibernate SVN: r17457 - in validator/trunk/hibernate-validator/src/main/docbook/en-US: modules and 1 other directory.
by hibernate-commits＠lists.jboss.org
Author: hardy.ferentschik
Date: 2009-09-01 10:42:20 -0400 (Tue, 01 Sep 2009)
New Revision: 17457
Modified:
validator/trunk/hibernate-validator/src/main/docbook/en-US/master.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:
started to work on documentation
Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml
===================================================================
--- validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml 2009-08-31 15:41:29 UTC (rev 17456)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml 2009-09-01 14:42:20 UTC (rev 17457)
@@ -62,21 +62,6 @@
<toc></toc>
- <preface>
- <title>Preface Beta Release</title>
-
- <para>This release has beta status, which means that this documenation is not yet 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>
-
- <para>Please report any problems or bugs in either <ulink
- url="http://opensource.atlassian.com/projects/hibernate/browse/HV">Jira
- Hibernate Validator</ulink> or on the <ulink
- url="http://forum.hibernate.org/viewforum.php?f=9">Validator
- Forum</ulink>.</para>
- </preface>
-
<preface id="preface" revision="2">
<title>Preface</title>
@@ -90,13 +75,14 @@
<para>JSR 303 - Bean Validation - defines a metadata model and API for
JavaBean validation. The default metadata source is annotations, with the
- ability to override and extend the meta-data through the use of XML
- validation descriptors. The API is not tied to a specific application tier
- or programming model. It is specifically not tied to either the web tier
- or the persistence tier, and is available for both server-side application
- programming, as well as rich client Swing application developers.</para>
+ ability to override and extend the meta-data through the use of XML. The
+ API is not tied to a specific application tier or programming model. It is
+ specifically not tied to either the web tier or the persistence tier, and
+ is available for both server-side application programming, as well as rich
+ client Swing application developers.</para>
- <para>Hibernate Validator is an implementation of this JSR.</para>
+ <para>Hibernate Validator is the reference implementation of this
+ JSR.</para>
</preface>
<!-- For the alpha release we will just include the getting started section, since the others are work in progress -->
@@ -112,14 +98,9 @@
<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" />
--->
-
- <!--
<xi:include href="modules/defineconstraints.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="modules/checkconstraints.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
--->
</book>
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-08-31 15:41:29 UTC (rev 17456)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml 2009-09-01 14:42:20 UTC (rev 17457)
@@ -28,10 +28,9 @@
<chapter id="validator-gettingstarted">
<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
- 303. Be sure to fulfill the following prerequisites in order to
- proceed:</para>
+ <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>
<itemizedlist>
<listitem>
@@ -41,11 +40,9 @@
<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 (help
- can be found <ulink
- url="http://maven.apache.org/download.html">here</ulink>) and a
- functioning internet connection is required to allow Maven for the
- download of all dependent libraries</para>
+ 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>
</listitem>
<listitem>
@@ -75,118 +72,34 @@
<para>Start by creating new Maven project using the Maven archetype plugin
as follows:</para>
- <para><programlisting>mvn archetype:generate -DarchetypeArtifactId=maven-archetype-quickstart</programlisting></para>
+ <para><programlisting>mvn archetype:generate \
+ -DarchetypeCatalog=http://repository.jboss.com/maven2/archetype-catalog.xml \
+ -DgroupId=com.mycompany \
+ -DartifactId=beanvalidation-gettingstarted \
+ -Dversion=1.0-SNAPSHOT \
+ -Dpackage=com.mycompany</programlisting></para>
- <para>and specify the requested properties:</para>
+ <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>
- <itemizedlist>
- <listitem>
- <para>groupId: An identifier for your company, e.g.
- com.mycompany</para>
- </listitem>
-
- <listitem>
- <para>artifactId: An identifier for the new project, e.g.
- beanvalidation-gettingstarted</para>
- </listitem>
-
- <listitem>
- <para>version: Initial version for the new project, e.g.
- 1.0-SNAPSHOT</para>
- </listitem>
-
- <listitem>
- <para>package: The top-level package for the new project, e.g.
- com.mycompany</para>
- </listitem>
- </itemizedlist>
-
- <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 (<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>
- <para>Add the dependency to hibernate-validator</para>
- </listitem>
-
- <listitem>
- <para>Add an SLF4J binding. As Hibernate Validator uses the logging
- facade <ulink url="http://www.slf4j.org/">SLF4J</ulink>, it can make
- use of your preferred logging API. In the following the binding to
- <ulink url="http://logging.apache.org/log4j/">log4j</ulink> is
- used.</para>
- </listitem>
-
- <listitem>
- <para>Set the compiler level to 1.5 (as we want to use
- annotations)</para>
- </listitem>
-
- <listitem>
- <para>Use JUnit 4 as testing framework</para>
- </listitem>
- </itemizedlist>
-
- <para>Having done this, your pom.xml should look like this:</para>
-
- <programlisting><project
- xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- <modelVersion>4.0.0</modelVersion>
- <groupId>com.mycompany</groupId>
- <artifactId>beanvalidation-gettingstarted</artifactId>
- <version>1.0-SNAPSHOT</version>
- <dependencies>
- <dependency>
- <groupId>org.hibernate</groupId>
- <artifactId>hibernate-validator</artifactId>
- <version>4.0.0.CR1</version>
- </dependency>
- <dependency>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- <version>1.4.2</version>
- <scope>runtime</scope>
- </dependency>
- <dependency>
- <groupId>junit</groupId>
- <artifactId>junit</artifactId>
- <version>4.5</version>
- <scope>test</scope>
- </dependency>
- </dependencies>
- <build>
- <plugins>
- <plugin>
- <artifactId>maven-compiler-plugin</artifactId>
- <configuration>
- <source>1.5</source>
- <target>1.5</target>
- </configuration>
- </plugin>
- </plugins>
- </build>
-</project></programlisting>
+ <para><programlisting>mvn test</programlisting>You should see some
+ compiling and testing action taking place. Time to look at the actual
+ code.</para>
</section>
<section id="validator-gettingstarted-createmodel" revision="1">
<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 your choice
- (for Eclipse, you may type mvn eclipse:eclipse to create a standard
- Eclipse project configuration OR you may use the <ulink
+ <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 create
- the following class as an exemplary domain object:</para>
+ url="http://wiki.netbeans.org/MavenBestPractices">here</ulink>) and open
+ the class <classname>Car</classname>:</para>
<para><programlisting>package com.mycompany;
@@ -361,9 +274,6 @@
<title>Where to go next?</title>
<para>That concludes our 5 minute tour through the world of the Bean
- Validation RI. We will complete this documentation in our coming releases.
- For now we recommend to refer to the JSR 303 specification directly for
- more examples. The 1.0.CR3 version of this specification is available
- <ulink url="http://in.relation.to/service/File/12014">here</ulink>.</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-08-31 15:41:29 UTC (rev 17456)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml 2009-09-01 14:42:20 UTC (rev 17457)
@@ -27,10 +27,6 @@
<chapter id="validator-usingvalidator">
<title>Object validation</title>
- <para>TODO: outline of the chapter. Should this be placed before <link
- lang="" linkend="validator-customconstraints">"Creating custom
- constraints"</link>?</para>
-
<section id="validator-usingvalidator-annotate" revision="1">
<title>Annotating your model</title>
@@ -293,7 +289,7 @@
cause each contained element to be validated, when the parent object is
validated.</para>
- <programlisting><![CDATA[package com.mycompany;
+ <programlisting>package com.mycompany;
import java.util.ArrayList;
import java.util.List;
@@ -309,16 +305,16 @@
@NotNull
@Valid
- private List<Person> passengers = new ArrayList<Person>();
+ private List&lt;Person&gt; passengers = new ArrayList&lt;Person&gt;();
- public Car(List<Person> passengers) {
+ public Car(List&lt;Person&gt; passengers) {
this.passengers = passengers;
}
//getters and setters ...
-}]]></programlisting>
+}</programlisting>
<para>If a <classname>Car</classname> instance is validated now, a
<classname>ConstraintValidation</classname> will be raised, if any of
15 years, 2 months
- 1
- 0