[hibernate-commits] Hibernate SVN: r15937 - in validator/trunk/hibernate-validator/src/main/docbook/en-US: modules and 1 other directory.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Wed Feb 11 06:55:31 EST 2009
Author: hardy.ferentschik
Date: 2009-02-11 06:55:31 -0500 (Wed, 11 Feb 2009)
New Revision: 15937
Modified:
validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml
Log:
updated the documentation for the alpha rlease
Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml
===================================================================
--- validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml 2009-02-11 10:00:19 UTC (rev 15936)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml 2009-02-11 11:55:31 UTC (rev 15937)
@@ -1,4 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!-- $Id:$ -->
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
@@ -22,75 +23,118 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
- <!ENTITY versionNumber "4.0.0.Alpha1">
- <!ENTITY copyrightYear "2009">
- <!ENTITY copyrightHolder "Red Hat Middleware, LLC. & Gunnar Morling">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY versionNumber "4.0.0.Alpha1">
+<!ENTITY copyrightYear "2009">
+<!ENTITY copyrightHolder "Red Hat Middleware, LLC.">
]>
-
<book lang="en">
- <bookinfo>
- <title>Hibernate Validator (Bean Validation API reference implementation)</title>
- <subtitle>Reference Guide</subtitle>
- <releaseinfo>&versionNumber;</releaseinfo>
- <productnumber>&versionNumber;</productnumber>
- <issuenum>1</issuenum>
- <mediaobject>
- <imageobject>
- <imagedata fileref="hibernate_logo_a.png" format="png" />
- </imageobject>
- </mediaobject>
- <copyright>
- <year>©rightYear;</year>
- <holder>©rightHolder;</holder>
- </copyright>
- <!-- include translators... -->
- </bookinfo>
+ <bookinfo>
+ <title>Hibernate Validator</title>
- <toc/>
+ <subtitle>JSR 303 Reference Implementation</subtitle>
+ <subtitle>Reference Guide</subtitle>
+
+ <releaseinfo>&versionNumber;</releaseinfo>
+
+ <productnumber>&versionNumber;</productnumber>
+
+ <issuenum>1</issuenum>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="hibernate_logo_a.png" align="center" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="hibernate_logo_a.png" depth="3cm" />
+ </imageobject>
+ </mediaobject>
+
+ <copyright>
+ <year>©rightYear;</year>
+
+ <holder>©rightHolder;</holder>
+ </copyright>
+ </bookinfo>
+
+ <toc></toc>
+
+ <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 latest
+ version of JSR 303:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Group inheritance using interfaces and implicit grouping</para>
+ </listitem>
+
+ <listitem>
+ <para>Implementation of the <classname>TraversableResolver</classname>
+ interface to allow integration with JPA</para>
+ </listitem>
+
+ <listitem>
+ <para>Polymorphism in graph validation </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 <ulink
+ url="http://hibernate.org/~emmanuel/validation/">JSR 303</ulink> 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>
- <para>Annotations are a very convenient and elegant way to specify
- invariant constraints for a domain model. You can, for example, express
- that a property should never be null, that the account balance should be
- strictly positive, etc. These domain model constraints are declared in the
- bean itself by annotating its properties. A validator can then read them
- and check for constraint violations. The validation mechanism can be
- executed in different layers in your application without having to
- duplicate any of these rules (presentation layer, data access layer).
- Following the DRY principle, Hibernate Validator has been designed for
- that purpose.</para>
+ <para>Validating data is a common task that occurs throughout an
+ application, from the presentation layer to the persistence layer. Often
+ the same validation logic is implemented in each layer, proving time
+ consuming and error-prone. To avoid duplication of these validations in
+ each layer, developers often bundle validation logic directly into the
+ domain model, cluttering domain classes with validation code that is, in
+ fact, metadata about the class itself.</para>
- <para>Hibernate Validator works at two levels. First, it is able to check
- in-memory instances of a class for constraint violations. Second, it can
- apply the constraints to the Hibernate metamodel and incorporate them into
- the generated database schema.</para>
+ <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>
- <para>Each constraint annotation is associated to a validator
- implementation responsible for checking the constraint on the entity
- instance. A validator can also (optionally) apply the constraint to the
- Hibernate metamodel, allowing Hibernate to generate DDL that expresses the
- constraint. With the appropriate event listener, you can execute the
- checking operation on inserts and updates done by Hibernate. Hibernate
- Validator is not limited to use with Hibernate. You can easily use it
- anywhere in your application as well as with any Java Persistence provider
- (entity listener provided).</para>
-
- <para>When checking instances at runtime, Hibernate Validator returns
- information about constraint violations in an array of
- <classname>InvalidValue</classname> s. Among other information, the
- <classname>InvalidValue</classname> contains an error description message
- that can embed the parameter values bundle with the annotation (eg. length
- limit), and message strings that may be externalized to a
- <classname>ResourceBundle</classname> .</para>
+ <para>Hibernate Validator is an 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 -->
+
<!--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/xmlconfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
@@ -98,7 +142,7 @@
<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" />
-->
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-02-11 10:00:19 UTC (rev 15936)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml 2009-02-11 11:55:31 UTC (rev 15937)
@@ -1,4 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!-- $Id:$ -->
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
@@ -25,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>Getting started with Bean Validation RI in 5 minutes</title>
+ <title>Getting started in 5 minutes</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
@@ -35,7 +36,7 @@
<itemizedlist>
<listitem>
<para>As the Bean Validation API expresses constraints by the means of
- annotations, Java version 5 is or later must be installed</para>
+ annotations, Java version 5 or later must be installed</para>
</listitem>
<listitem>
@@ -46,28 +47,28 @@
functioning internet connection is required to allow Maven for the
download of all dependent libraries</para>
</listitem>
+
+ <listitem>
+ <para>Once Maven is installed you should configure your remote
+ repository by adding the following to your
+ <filename>settings.xml</filename>: <programlisting><repositories>
+ <repository>
+ <id>jboss</id>
+ <url>http://repository.jboss.com/maven2</url>
+ <releases>
+ <enabled>true</enabled>
+ </releases>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ </repository>
+</repositories></programlisting>More information about
+ <filename>settings.xml</filename> can be found in the <ulink
+ url="http://maven.apache.org/ref/2.0.8/maven-settings/settings.html">Maven
+ Local Settings Model</ulink>.</para>
+ </listitem>
</itemizedlist>
- <section id="validator-gettingstarted-buildri" revision="1">
- <title>Build RI. TODO GM: Remove, if RI is in repo</title>
-
- <para>As the Bean Validation RI is not yet published in any Maven
- repository, you have to check it out from the Subversion repository at
- JBoss and build it yourself. The project can be checked out as
- follows:</para>
-
- <programlisting>svn co http://anonsvn.jboss.org/repos/hibernate/validator/trunk/</programlisting>
-
- <para>If all files are checked out, change into the trunk dir and build
- the reference implementation by running</para>
-
- <programlisting>mvn install</programlisting>
-
- <para>If the build has completed, the JSR 303 API and the reference
- implementation have been installed into your local Maven repository and
- can now be used in your projects.</para>
- </section>
-
<section id="validator-gettingstarted-createproject" revision="1">
<title>Setting up a new Maven project</title>
@@ -123,8 +124,7 @@
</listitem>
</itemizedlist>
- <para>Having done this, your pom.xml should look like this (TODO GM: keep
- an eye on versions):</para>
+ <para>Having done this, your pom.xml should look like this:</para>
<programlisting><project
xmlns="http://maven.apache.org/POM/4.0.0"
@@ -144,12 +144,12 @@
<dependency>
<groupId>javax.validation</groupId>
<artifactId>validation-api</artifactId>
- <version>1.0.0-SNAPSHOT</version>
+ <version>1.0.Beta3</version>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-validator</artifactId>
- <version>1.0.0-SNAPSHOT</version>
+ <version>4.0.0.Alpha1</version>
</dependency>
</dependencies>
<build>
More information about the hibernate-commits
mailing list