HV-381

hibernate-validator/src/main/docbook/en-US/master.xml

@@ -74,10 +74,10 @@
 
     <xi:include href="modules/integration.xml"
                 xmlns:xi="http://www.w3.org/2001/XInclude"/>
-
-    <xi:include href="modules/programmaticapi.xml"
+                
+    <xi:include href="modules/customoptions.xml"
                 xmlns:xi="http://www.w3.org/2001/XInclude"/>
-
+              
 	<xi:include href="modules/annotationprocessor.xml"
 			    xmlns:xi="http://www.w3.org/2001/XInclude"/>
 

hibernate-validator/src/main/docbook/en-US/modules/bootstrapping.xml

@@ -203,7 +203,7 @@ Validator validator = factory.getValidator();
       <methodname>Configuration.getDefaultMessageInterpolator()</methodname>.</para>
     </tip>
 
-    <section>
+    <section id="section-resource-bundle-locator" label="">
       <title>ResourceBundleLocator</title>
 
       <para>A common use case is the ability to specify your own resource

hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml

@@ -0,0 +1,212 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+	~ JBoss, Home of Professional Open Source
+	~ Copyright 2009, Red Hat, Inc. and/or its affiliates, and individual contributors
+	~ by the @authors tag. See the copyright.txt in the distribution for a
+	~ full listing of individual contributors.
+	~
+	~ Licensed under the Apache License, Version 2.0 (the "License");
+	~ you may not use this file except in compliance with the License.
+	~ You may obtain a copy of the License at
+	~ http://www.apache.org/licenses/LICENSE-2.0
+	~ Unless required by applicable law or agreed to in writing, software
+	~ distributed under the License is distributed on an "AS IS" BASIS,
+	~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	~ See the License for the specific language governing permissions and
+	~ limitations under the License.
+-->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "../hv.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="chapter-custom-options">
+  <title>Hibernate Validator specific configuration</title>
+
+  <note>
+    <para>Use of the features described in the following sections is not
+    portable between Bean Validation providers/implementations.</para>
+  </note>
+
+  <para>The Bean Validation specification allows implementators to add
+  provider specific options. The easiest way to do this is via
+  <methodname>Configuration.addProperty(String name, String
+  value)</methodname> which allows to pass any arbitrary property. If you want
+  to expose the option programmatically (in a type-safe manner) there are
+  three other options depending on where you want to make the option
+  available.</para>
+
+  <para>You can add the option onto a custom
+  <classname>Configuration</classname> instance. This custom configuration can
+  be explicitly requested during the bootstrapping process using
+  <methodname>Validation.byProvider(Class&lt;U&gt; providerType)</methodname>.
+  This is the approach taken for exposing the programmatic constraint
+  configuration API (see <xref linkend="programmaticapi" /> ) as well as the
+  abiltiy to configure a custom ResourceBundleLocator (see <xref
+  linkend="section-resource-bundle-locator" />).</para>
+
+  <para>You cam also add the option accessible on you
+  <classname>ValidatorFactory</classname> implementation and then access it
+  via <methodname>ValidatorFactory.unwrap(Class&lt;T&gt; type)</methodname>
+  (see <xref linkend="example-fail-fast-factory" />).</para>
+
+  <para>Last but not least, you can also add the option to your
+  <classname>Validator</classname> implementation and unwrap the
+  <classname>Validator</classname> instance itself using
+  <methodname>Validator.unwrap(Class&lt;T&gt; type)</methodname>. This is how
+  the method level validation API is exposed in Hibernate Validator (see
+  ?).</para>
+
+  <para>In the following sections weare having a closer look at some of the
+  Hibernate Validator specific features.</para>
+
+  <section>
+    <title>Fail fast mode</title>
+
+    <para>Hibernate Validator allows to return from the current validation as
+    soon as the first constraint violation occurs. This is called the fail
+    fast mode and can be useful for validation of large object graphs where
+    you are only interested whether there is a constraint violation or not.
+    <xref linkend="example-fail-fast-property" />, <xref
+    linkend="example-fail-fast-configuration" /> and <xref
+    linkend="example-fail-fast-factory" /> show multiple ways to enable the
+    fail fast mode.</para>
+
+    <example floatstyle="" id="example-fail-fast-property">
+      <title>Enabling <option>failFast</option> via a property</title>
+
+      <programlisting>HibernateValidatorConfiguration configuration = Validation.byProvider( HibernateValidator.class ).configure();
+ValidatorFactory factory = configuration.addProperty( "hibernate.validator.fail_fast", "true" ).buildValidatorFactory();
+Validator validator = factory.getValidator();
+
+// do some actual fail fast validation
+...</programlisting>
+    </example>
+
+    <example id="example-fail-fast-configuration">
+      <title>Enabling <option>failFast</option> at the
+      <classname>Configuration</classname> level</title>
+
+      <programlisting>HibernateValidatorConfiguration configuration = Validation.byProvider( HibernateValidator.class ).configure();
+ValidatorFactory factory = configuration.failFast( true ).buildValidatorFactory();
+Validator validator = factory.getValidator();
+
+// do some actual fail fast validation
+...</programlisting>
+    </example>
+
+    <example id="example-fail-fast-factory">
+      <title>Enabling <option>failFast</option> at the
+      <classname>ValidatorFactory</classname> level</title>
+
+      <programlisting>HibernateValidatorConfiguration configuration = Validation.byProvider( HibernateValidator.class ).configure();
+ValidatorFactory factory = configuration.buildValidatorFactory();
+
+Validator validator = factory.getValidator();
+
+// do some non fail fast validation
+...
+
+validator = factory.unwrap( HibernateValidatorFactory.class )
+            .usingContext()
+            .failFast( true )
+            .getValidator();
+
+// do fail fast validation
+...</programlisting>
+    </example>
+  </section>
+
+  <section id="programmaticapi">
+    <title>Programmatic constraint definition</title>
+
+    <para>Hibernate Validator allows to configure constraints not only via
+    annotations and xml, but also via a programmatic API. This API can be used
+    exclusively or in combination with annotations and xml. If used in
+    combination programmatic constraints are additive to otherwise configured
+    constraints.</para>
+
+    <para>The programmatic API is centered around the
+    <classname>ConstraintMapping</classname> class which can be found together
+    with its supporting classes in the
+    <package>org.hibernate.validator.cfg</package> package.
+    <classname>ConstraintMapping</classname> is the entry point to a fluent
+    API allowing the definition of constraints. <xref lang=""
+    linkend="example-constraint-mapping" /> shows how the API can be
+    used.</para>
+
+    <para><example id="example-constraint-mapping">
+        <title>Programmatic constraint definition</title>
+
+        <programlisting>ConstraintMapping mapping = new ConstraintMapping();
+mapping.type( Car.class )
+    .property( "manufacturer", FIELD )
+        .constraint( NotNullDef.class )
+    .property( "licensePlate", FIELD )
+        .constraint( NotNullDef.class )
+        .constraint( SizeDef.class )
+            .min( 2 )
+            .max( 14 )
+    .property( "seatCount", FIELD )
+        .constraint( MinDef.class )
+            .value ( 2 )
+.type( RentalCar.class )
+    .property( "rentalStation", METHOD)
+        .constraint( NotNullDef.class );      </programlisting>
+      </example></para>
+
+    <para>As you can see you can configure constraints on multiple classes and
+    properties using method chaining. The constraint definition classes
+    <classname>NotNullDef</classname>, <classname>SizeDef</classname> and
+    <classname>MinDef</classname> are helper classes which allow to configure
+    constraint parameters in a type-safe fashion. Definition classes exists
+    for all built-in constraints in the
+    <classname>org.hibernate.validator.cfg.defs</classname> package. For a
+    custom constraint you can either create your own definition class
+    extending <classname>ConstraintDef</classname> or you can use the
+    <classname>genericConstraint</classname> method as seen in <xref
+    linkend="example-generic-constraint-mapping" />.</para>
+
+    <para><example id="example-generic-constraint-mapping">
+        <title>Programmatic constraint definition using
+        <classname>GenericConstraintDef</classname></title>
+
+        <programlisting>ConstraintMapping mapping = new ConstraintMapping();
+mapping.type( Car.class )
+    .property( "licensePlate", FIELD )
+        .genericConstraint( CheckCase.class )
+            .param( "value", CaseMode.UPPER );   </programlisting>
+      </example></para>
+
+    <para>Last but not least, you can also define cascading constraints as
+    well as the default group sequence of an entity.</para>
+
+    <para><example>
+        <title>Cascading constraints and group redefinition</title>
+
+        <programlisting>ConstraintMapping mapping = new ConstraintMapping();
+mapping.type( Car.class )
+    .valid( "driver", FIELD )
+.type( RentalCar.class)
+    .defaultGroupSequence( RentalCar.class, CarChecks.class ); </programlisting>
+      </example></para>
+
+    <para>Once you have your <classname>ConstraintMapping</classname> you will
+    have to pass it to the configuration. Since the programmatic configuration
+    is not part of the official Bean Validation specification you will have to
+    get hold of the Hibernate Validator specific configuration instance. See
+    <xref linkend="example-hibernate-specific-config" />.</para>
+
+    <para><example id="example-hibernate-specific-config">
+        <title>Creating a Hibernate Validator specific configuration</title>
+
+        <programlisting>ConstraintMapping mapping = new ConstraintMapping();
+// configure mapping instance
+
+HibernateValidatorConfiguration config = Validation.byProvider( HibernateValidator.class ).configure();
+config.addMapping( mapping );
+ValidatorFactory factory = config.buildValidatorFactory();
+Validator validator = factory.getValidator();</programlisting>
+      </example></para>
+  </section>
+</chapter>