diff --git a/documentation/src/main/docbook/en-US/modules/customoptions.xml b/documentation/src/main/docbook/en-US/modules/customoptions.xml
index c49a46d324..d16b2917b5 100644
--- a/documentation/src/main/docbook/en-US/modules/customoptions.xml
+++ b/documentation/src/main/docbook/en-US/modules/customoptions.xml
@@ -38,7 +38,7 @@
Public API
Let's start, however, with a look at the public API of Hibernate
- Validator. lists all packages
+ Validator. lists all packages
belonging to this API and describes their purpose.
Any packages not listed in that table are internal packages of
@@ -71,7 +71,7 @@
This package contains the classes used by the Bean
Validation bootstrap mechanism (eg. validation provider,
configuration class). For more details see .
+ linkend="validator-bootstrapping"/>.
@@ -86,33 +86,36 @@
ConstraintMapping class and in package
org.hibernate.validator.cfg.defs all constraint
definitions. For more details see .
+ linkend="programmaticapi"/>.
- org.hibernate.validator.constraints
+ org.hibernate.validator.constraints,
+ org.hibernate.validator.constraints.br
In addition to Bean Validation constraints, Hibernate
- Validator provides some useful custom constraints. This package
- contains all custom annotation classes. For more details see .
+ Validator provides some useful custom constraints. These packages
+ contain all custom annotation classes. For more details see .
- org.hibernate.validator.group
+ org.hibernate.validator.group,
+ org.hibernate.validator.spi.group
With Hibernate Validator you can define dynamic default
- group sequences in function of the validated object state. This
- package contains all classes needed to use this feature
+ group sequences in function of the validated object state. These
+ packages contain all classes needed to use this feature
(GroupSequenceProvider annotation and
DefaultGroupSequenceProvider contract). For
more details see .
+ linkend="section-default-group-class"/>.
org.hibernate.validator.messageinterpolation,
- org.hibernate.validator.resourceloading
+ org.hibernate.validator.resourceloading,
+ org.hibernate.validator.spi.resourceloading
These packages contain the classes related to constraint
message interpolation. The first package contains two
@@ -120,13 +123,13 @@
first one,
ValueFormatterMessageInterpolator allows to
interpolate the validated value into the constraint message, see
- . The second
+ . The second
implementation named
ResourceBundleMessageInterpolator is the
implementation used by default by Hibernate Validator. This
implementation relies on a
ResourceBundleLocator, see . Hibernate Validator
+ linkend="section-resource-bundle-locator"/>. Hibernate Validator
provides different ResourceBundleLocator
implementations located in the package
org.hibernate.validator.resourceloading.
@@ -148,6 +151,16 @@
+
+
+ The public packages of Hibernate Validator fall into two
+ categories: while the actual API parts are intended to be
+ invoked or used by clients
+ (e.g. the API for programmatic constraint declaration or the custom
+ constraints), the SPI (service provider interface) packages contain
+ interfaces which are intended to be implemented by
+ clients (e.g. ResourceBundleLocator).
+
@@ -158,9 +171,9 @@
occurs. This is called the fail fast mode and can be
useful for validation of large object graphs where one is only interested
whether there is a constraint violation or not. , and show multiple ways to enable the
+ linkend="example-fail-fast-property"/>, and show multiple ways to enable the
fail fast mode.
@@ -263,7 +276,7 @@ validator = factory.unwrap( HibernateValidatorFactory.class )
Defining method-level constraints
- demonstrates
+ demonstrates
the definition of method-level constraints.
Using method-level constraints
@@ -303,7 +316,7 @@ validator = factory.unwrap( HibernateValidatorFactory.class )
Using the @Valid annotation it's also
possible to define that a cascaded validation of parameter or return
value objects shall be performed. An example can be found in .
+ lang="" linkend="example-cascaded-method-constraints"/>.
Cascaded validation of method-level constraints
@@ -345,7 +358,7 @@ validator = factory.unwrap( HibernateValidatorFactory.class )
engine, a
javax.validation.ConstraintDeclarationException
will be thrown. In some examples for
+ linkend="example-illegal-method-constraints"/> some examples for
illegal parameter constraints declarations are shown.
@@ -392,10 +405,10 @@ public class CarImpl implements ICar {
the interface
org.hibernate.validator.method.MethodValidator.
- As shown in
- this interface defines methods for the evaluation of parameter as well
- as return value constraints and for retrieving an extended type
- descriptor providing method constraint related meta data.
+ As shown in this
+ interface defines methods for the evaluation of parameter as well as
+ return value constraints and for retrieving an extended type descriptor
+ providing method constraint related meta data.
The MethodValidator interface
@@ -415,7 +428,7 @@ public class CarImpl implements ICar {
To retrieve a method validator get hold of an instance of HV's
javax.validation.Validator implementation and
unwrap it to MethodValidator as shown in .
+ lang="" linkend="example-retrieving-methodvalidator"/>.
Retrieving a MethodValidator
@@ -432,7 +445,7 @@ public class CarImpl implements ICar {
MethodValidator each return a
Set<MethodConstraintViolation>. The type
MethodConstraintViolation (see ) extends
+ linkend="example-methodconstraintviolation"/>) extends
javax.validation.ConstraintViolation and provides
additional method level validation specific information such as the
method and index of the parameter which caused the constraint
@@ -488,14 +501,14 @@ public class CarImpl implements ICar {
Retrieving method-level constraint meta data
- As outlined in
+ As outlined in
the Bean Validation API provides rich capabilities for retrieving
constraint related meta data. Hibernate Validator extends this API and
allows to retrieve constraint meta data also for method-level
constraints.
- shows
- how to use this extended API to retrieve constraint meta data for the
+ shows how
+ to use this extended API to retrieve constraint meta data for the
rentCar() method from the
RentalStation type.
@@ -547,7 +560,7 @@ assertEquals(startDateParameter.findConstraints().getConstraintDescriptors().siz
package org.hibernate.validator.cfg. Starting with the
instantiation of a new ConstraintMapping,
constraints can be defined in a fluent manner as shown in .
+ linkend="example-constraint-mapping"/>.
Programmatic constraint definition
@@ -577,7 +590,7 @@ mapping.type( Car.class )
For custom constraints you can either create your own definition
classes extending ConstraintDef or you can use
GenericConstraintDef as seen in .
+ linkend="example-generic-constraint-mapping"/>.
Programmatic constraint definition using
@@ -591,7 +604,7 @@ mapping.type( Car.class )
Not only standard class- and property-level constraints but also
method constraints can be configured using the API. As shown in methods are
+ lang="" linkend="example-method-constraint-mapping"/> methods are
identified by their name and their parameters (if there are any). Having
selected a method, constraints can be placed on the method's parameters
and/or return value.
@@ -617,7 +630,7 @@ mapping.type( Car.class )
Using the API it's also possible to mark properties, method
parameters and method return values as cascading (equivalent to annotating
them with @Valid). An example can be found in .
+ lang="" linkend="example-cascading-constraints"/>.
Marking constraints for cascaded validation
@@ -642,7 +655,7 @@ mapping.type( Car.class )
Last but not least you can configure the default group sequence or
the default group sequence provider of a type as shown in .
+ linkend="example-sequences"/>.
Configuration of default group sequence and default group
sequence provider
@@ -657,7 +670,7 @@ mapping.type( Car.class )
be passed to the configuration. Since the programmatic API is not part of
the official Bean Validation specification you need to get hold of a
HibernateValidatorConfiguration instance as shown
- in .
+ in .
Creating a Hibernate Validator specific configuration
@@ -676,7 +689,7 @@ Validator validator = factory.getValidator();
Boolean composition for constraint composition
As per Bean Validation specification the constraints of a composed
- constraint (see ) are all
+ constraint (see ) are all
combined via a logical AND. This means all of the
composing constraints need to return true in order
for an overall successful validation. Hibernate Validator offers an
@@ -687,7 +700,7 @@ Validator validator = factory.getValidator();
CompositionType with its values
AND, OR and
ALL_FALSE. shows how to build a
+ linkend="example-boolean-constraint-composition"/> shows how to build a
composing constraint where only one of the constraints has to be
successful in order to pass the validation. Either the validated string is
all lowercased or it is between two and three characters long.