Documente Academic
Documente Profesional
Documente Cultură
Reference Guide
4.1.0.Final
iii
Hibernate Validator
iv
Preface
Validating data is a common task that occurs throughout any 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 which is really metadata about the class itself.
JSR 303 - Bean Validation - defines a metadata model and API for entity validation. The default
metadata source is annotations, with the 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.
v
vi
Chapter 1.
Getting started
This chapter will show you how to get started with Hibernate Validator, the reference
implementation (RI) of Bean Validation. For the following quickstart you need:
• A JDK >= 5
<repositories>
<repository>
<id>jboss</id>
<url>http://repository.jboss.com/maven2</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
More information about settings.xml can be found in the Maven Local Settings Model [http://
maven.apache.org/ref/2.0.8/maven-settings/settings.html].
Note
Hibernate Validator uses JAXB for XML parsing. JAXB is part of the Java Class
Library since Java 6 which means that if you run Hibernate Validator with Java 5
you will have to add additional JAXB dependencies. Using maven you have to add
the following dependencies:
<dependency>
<groupId>javax.xml.bind</groupId>
<artifactId>jaxb-api</artifactId>
<version>2.2</version>
</dependency>
<dependency>
<groupId>com.sun.xml.bind</groupId>
<artifactId>jaxb-impl</artifactId>
<version>2.1.12</version>
1
Chapter 1. Getting started
</dependency>
if you are using the SourceForge package you find the necessary libraries in the
lib/jdk5 directory. In case you are not using the XML configuration you can
also disable it explicitly by calling Configuration.ignoreXmlConfiguration()
during ValidationFactory creation. In this case the JAXB dependencies are not
needed.
Maven will create your project in the directory hv-quickstart. Change into this directory and run:
mvn test
Maven will compile the example code and run the implemented unit tests. Let's have a look at
the actual code.
package com.mycompany;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
@NotNull
private String manufacturer;
2
Validating constraints
@NotNull
@Size(min = 2, max = 14)
private String licensePlate;
@Min(2)
private int seatCount;
@NotNull, @Size and @Min are so-called constraint annotations, that we use to declare
constraints, which shall be applied to the fields of a Car instance:
• licensePlate shall never be null and must be between 2 and 14 characters long
package com.mycompany;
import java.util.Set;
import javax.validation.ConstraintViolation;
import javax.validation.Validation;
import javax.validation.Validator;
import javax.validation.ValidatorFactory;
import org.junit.BeforeClass;
import org.junit.Test;
@BeforeClass
public static void setUp() {
ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
validator = factory.getValidator();
3
Chapter 1. Getting started
@Test
public void manufacturerIsNull() {
Car car = new Car(null, "DD-AB-123", 4);
Set<ConstraintViolation<Car>> constraintViolations =
validator.validate(car);
assertEquals(1, constraintViolations.size());
assertEquals("may not be null", constraintViolations.iterator().next().getMessage());
}
@Test
public void licensePlateTooShort() {
Car car = new Car("Morris", "D", 4);
Set<ConstraintViolation<Car>> constraintViolations =
validator.validate(car);
assertEquals(1, constraintViolations.size());
assertEquals("size must be between 2 and
14", constraintViolations.iterator().next().getMessage());
}
@Test
public void seatCountTooLow() {
Car car = new Car("Morris", "DD-AB-123", 1);
Set<ConstraintViolation<Car>> constraintViolations =
validator.validate(car);
assertEquals(1, constraintViolations.size());
assertEquals("must be greater than or equal to
2", constraintViolations.iterator().next().getMessage());
}
@Test
public void carIsValid() {
Car car = new Car("Morris", "DD-AB-123", 2);
Set<ConstraintViolation<Car>> constraintViolations =
validator.validate(car);
assertEquals(0, constraintViolations.size());
}
}
In the setUp() method we get a Validator instance from the ValidatorFactory. A Validator
instance is thread-safe and may be reused multiple times. For this reason we store it as field of
our test class. We can use the Validator now to validate the different car instances in the test
methods.
The validate() method returns a set of ConstraintViolation instances, which we can iterate
in order to see which validation errors occurred. The first three test methods show some expected
constraint violations:
4
Where to go next?
Note that we only use classes from the package javax.validation 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.
5
6
Chapter 2.
Note
Not all constraints can be placed on all of these levels. In fact, none of the
default constraints defined by Bean Validation can be placed at class level.
The java.lang.annotation.Target annotation in the constraint annotation itself
determines on which elements a constraint can be placed. See Chapter 3, Creating
custom constraints for more information.
package com.mycompany;
import javax.validation.constraints.NotNull;
@NotNull
private String manufacturer;
@AssertTrue
private boolean isRegistered;
7
Chapter 2. Validation step by...
When using field level constraints field access strategy is used to access the value to be validated.
This means the bean validation provider directly accesses the instance variable and does not
invoke the property accessor method also if such a method exists.
Note
Note
Note
package com.mycompany;
import javax.validation.constraints.AssertTrue;
import javax.validation.constraints.NotNull;
@NotNull
public String getManufacturer() {
return manufacturer;
}
8
Class-level constraints
@AssertTrue
public boolean isRegistered() {
return isRegistered;
}
When using property level constraints property access strategy is used to access the value to be
validated. This means the bean validation provider accesses the state via the property accessor
method.
Tip
It is recommended to stick either to field or property annotation within one class. It
is not recommended to annotate a field and the accompanying getter method as
this would cause the field to be validated twice.
package com.mycompany;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
@PassengerCount
public class Car {
@NotNull
private String manufacturer;
9
Chapter 2. Validation step by...
@NotNull
@Size(min = 2, max = 14)
private String licensePlate;
@Min(2)
private int seatCount;
When validating an object that implements an interface or extends another class, all constraint
annotations on the implemented interface and parent class apply in the same manner as the
constraints specified on the validated object itself. To make things clearer let's have a look at the
following example:
package com.mycompany;
import javax.validation.constraints.NotNull;
@NotNull
public String getRentalStation() {
return rentalStation;
}
10
Object graphs
Our well-known class Car is now extended by RentalCar with the additional property rentalStation.
If an instance of RentalCar is validated, not only the @NotNull constraint on rentalStation is
validated, but also the constraint on manufacturer from the parent class.
The same would hold true, if Car were an interface implemented by RentalCar.
Constraint annotations are aggregated if methods are overridden. If RentalCar would override
the getManufacturer() method from Car any constraints annotated at the overriding method
would be evaluated in addition to the @NotNull constraint from the super-class.
package com.mycompany;
import javax.validation.constraints.NotNull;
@NotNull
private String name;
package com.mycompany;
import javax.validation.Valid;
import javax.validation.constraints.NotNull;
11
Chapter 2. Validation step by...
@NotNull
@Valid
private Person driver;
If an instance of Car is validated, the referenced Person object will be validated as well, as the
driver field is annotated with @Valid. Therefore the validation of a Car will fail if the name field of
the referenced Person instance is null.
Object graph validation also works for collection-typed fields. That means any attributes that
• are arrays
• implement java.util.Map
can be annotated with @Valid, which will cause each contained element to be validated, when
the parent object is validated.
package com.mycompany;
import java.util.ArrayList;
import java.util.List;
import javax.validation.Valid;
import javax.validation.constraints.NotNull;
@NotNull
@Valid
private List<Person> passengers = new ArrayList<Person>();
12
Validating constraints
Note
null values are getting ignored when validating object graphs.
For other ways of obtaining a Validator instance see Chapter 5, Bootstrapping. For now we just
want to see how we can use the Validator instance to validate entity instances.
All three methods return a Set<ConstraintViolation>. The set is empty, if the validation
succeeds. Otherwise a ConstraintViolation instance is added for each violated constraint.
All the validation methods have a var-args parameter which can be used to specify, which
validation groups shall be considered when performing the validation. If the parameter is not
specified the default validation group (javax.validation.groups.Default) will be used. We will
go into more detail on the topic of validation groups in Section 2.3, “Validating groups”
2.2.2.1. validate
Use the validate() method to perform validation of all constraints of a given entity instance (see
Example 2.9, “Usage of Validator.validate()” ).
13
Chapter 2. Validation step by...
assertEquals(1, constraintViolations.size());
assertEquals("may not be null", constraintViolations.iterator().next().getMessage());
2.2.2.2. validateProperty
With help of the validateProperty() a single named property of a given object can be validated.
The property name is the JavaBeans property name.
assertEquals(1, constraintViolations.size());
assertEquals("may not be null", constraintViolations.iterator().next().getMessage());
Validator.validateProperty is for example used in the integration of Bean Validation into JSF
2 (see Section 6.4, “Presentation layer validation”).
2.2.2.3. validateValue
Using the validateValue() method you can check, whether a single property of a given class
can be validated successfully, if the property had the specified value:
assertEquals(1, constraintViolations.size());
assertEquals("may not be null", constraintViolations.iterator().next().getMessage());
Note
14
ConstraintViolation methods
15
Chapter 2. Validation step by...
Since the braces { and } have special meaning in the messages they need to be escaped if they
are used literally. The following The following rules apply:
If the default message interpolator does not fit your requirements it is possible to plug a custom
MessageInterpolator when the ValidatorFactory gets created. This can be seen in Chapter 5,
Bootstrapping.
Note
When more than one group is requested, the order in which the groups
are evaluated is not deterministic. If no group is specified the default group
javax.validation.groups.Default is assumed.
16
Validating groups
Next we have the class Driver (Example 2.13, “Driver”) extending Person. Here we are adding
the properties age and hasDrivingLicense. In order to drive you must be at least 18 (@Min(18))
and you must have a driving license (@AssertTrue). Both constraints defined on these properties
belong to the group DriverChecks. As you can see in Example 2.14, “Group interfaces” the group
DriverChecks is just a simple tagging interface. Using interfaces makes the usage of groups type
safe and allows for easy refactoring. It also means that groups can inherit from each other via
class inheritance.
Note
The Bean Validation specification does not enforce that groups have to be
interfaces. Non interface classes could be used as well, but we recommend to stick
to interfaces.
@AssertTrue(message = "You first have to pass the driving test", groups = DriverChecks.class)
public boolean hasDrivingLicense;
17
Chapter 2. Validation step by...
Last but not least we add the property passedVehicleInspection to the Car class (Example 2.15,
“Car”) indicating whether a car passed the road worthy tests.
@NotNull
@Size(min = 2, max = 14)
private String licensePlate;
@Min(2)
private int seatCount;
@Valid
private Driver driver;
Overall three different groups are used in our example. Person.name, Car.manufacturer,
Car.licensePlate and Car.seatCount all belong to the Default group. Driver.age
and Driver.hasDrivingLicense belong to DriverChecks and last but not least
Car.passedVehicleInspection belongs to the group CarChecks. Example 2.16, “Drive away” shows
how passing different group combinations to the Validator.validate method result in different
validation results.
@BeforeClass
public static void setUp() {
ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
validator = factory.getValidator();
}
18
Group sequences
@Test
public void driveAway() {
// create a car and check that everything is ok with it.
Car car = new Car( "Morris", "DD-AB-123", 2 );
Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );
assertEquals( 0, constraintViolations.size() );
// now let's add a driver. He is 18, but has not passed the driving test yet
Driver john = new Driver( "John Doe" );
john.setAge( 18 );
car.setDriver( john );
constraintViolations = validator.validate( car, DriverChecks.class );
assertEquals( 1, constraintViolations.size() );
assertEquals( "You first have to pass the driving
test", constraintViolations.iterator().next().getMessage() );
First we create a car and validate it using no explicit group. There are no validation errors,
even though the property passedVehicleInspection is per default false. However, the constraint
defined on this property does not belong to the default group. Next we just validate the CarChecks
group which will fail until we make sure that the car passes the vehicle inspection. When we then
add a driver to the car and validate against DriverChecks we get again a constraint violation due
to the fact that the driver has not yet passed the driving test. Only after setting passedDrivingTest
to true the validation against DriverChecks will pass.
Last but not least, we show that all constraints are passing by validating against all defined groups.
By default, constraints are evaluated in no particular order and this regardless of which groups
they belong to. In some situations, however, it is useful to control the order of the constraints
evaluation. In our example from Section 2.3, “Validating groups” we could for example require
that first all default car constraints are passing before we check the road worthiness of the car.
Finally before we drive away we check the actual driver constraints. In order to implement such an
19
Chapter 2. Validation step by...
order one would define a new interface and annotate it with @GroupSequence defining the order
in which the groups have to be validated.
Note
If at least one constraints fails in a sequenced group none of the constraints of the
following groups in the sequence get validated.
Warning
The usage of the new sequence could then look like in Example 2.18, “Usage of a group
sequence”.
@Test
public void testOrderedChecks() {
Car car = new Car( "Morris", "DD-AB-123", 2 );
car.setPassedVehicleInspection( true );
The @GroupSequence annotation also fulfills a second purpose. It allows you to redefine what the
Default group means for a given class. To redefine Default for a class, place a @GroupSequence
20
Built-in constraints
annotation on the class. The defined groups in the annotation express the sequence of groups that
substitute Default for this class. Example 2.19, “RentalCar” introduces a new class RentalCar
with a redfined default group. With this definition the check for all three groups can be rewritten
as seen in Example 2.20, “testOrderedChecksWithRedefinedDefault”.
@Test
public void testOrderedChecksWithRedefinedDefault() {
RentalCar rentalCar = new RentalCar( "Morris", "DD-AB-123", 2 );
rentalCar.setPassedVehicleInspection( true );
Note
Due to the fact that there cannot be a cyclic dependency in the group and group
sequence definitions one cannot just add Default to the sequence redefining
Default for a class. Instead the class itself should be added!
21
Chapter 2. Validation step by...
22
Built-in constraints
23
Chapter 2. Validation step by...
24
Built-in constraints
25
Chapter 2. Validation step by...
26
Built-in constraints
Note
In some cases these built-in constraints will not fulfill your requirements. In this case you can
literally in a minute write your own constraints. We will discuss this in Chapter 3, Creating custom
constraints
27
28
Chapter 3.
• Implement a validator
First we need a way to express the two case modes. We might use String constants, but a better
way to go is to use a Java 5 enum for that purpose:
package com.mycompany;
Now we can define the actual constraint annotation. If you've never designed an annotation before,
this may look a bit scary, but actually it's not that hard:
package com.mycompany;
import java.lang.annotation.Documented;
29
Chapter 3. Creating custom co...
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import javax.validation.Constraint;
import javax.validation.Payload;
CaseMode value();
An annotation type is defined using the @interface keyword. All attributes of an annotation type
are declared in a method-like manner. The specification of the Bean Validation API demands, that
any constraint annotation defines
• an attribute message that returns the default key for creating error messages in case the
constraint is violated
• an attribute groups that allows the specification of validation groups, to which this constraint
belongs (see Section 2.3, “Validating groups”). This must default to an empty array of type
Class<?>.
• an attribute payload that can be used by clients of the Bean Validation API to assign custom
payload objects to a constraint. This attribute is not used by the API itself.
Tip
30
The constraint validator
// ...
}
Besides those three mandatory attributes (message, groups and payload) we add another
one allowing for the required case mode to be specified. The name value is a special one,
which can be omitted upon using the annotation, if it is the only attribute specified, as e.g. in
@CheckCase(CaseMode.UPPER).
In addition we annotate the annotation type with a couple of so-called meta annotations:
• @Target({ METHOD, FIELD, ANNOTATION_TYPE }): Says, that methods, fields and annotation
declarations may be annotated with @CheckCase (but not type declarations e.g.)
• @Documented: Says, that the use of @CheckCase will be contained in the JavaDoc of elements
annotated with it
package com.mycompany;
import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
31
Chapter 3. Creating custom co...
if (object == null)
return true;
if (caseMode == CaseMode.UPPER)
return object.equals(object.toUpperCase());
else
return object.equals(object.toLowerCase());
}
The ConstraintValidator interface defines two type parameters, which we set in our
implementation. The first one specifies the annotation type to be validated (in our example
CheckCase), the second one the type of elements, which the validator can handle (here String).
The implementation of the validator is straightforward. The initialize() method gives us access
to the attribute values of the annotation to be validated. In the example we store the CaseMode in
a field of the validator for further usage.
In the isValid() method we implement the logic, that determines, whether a String is valid
according to a given @CheckCase annotation or not. This decision depends on the case mode
retrieved in initialize(). As the Bean Validation specification recommends, we consider null
values as being valid. If null is not a valid value for an element, it should be annotated with
@NotNull explicitly.
Example 3.3, “Implementing a constraint validator for the constraint CheckCase” relies on the
default error message generation by just returning true or false from the isValid call. Using
the passed ConstraintValidatorContext object it is possible to either add additional error
messages or completely disable the default error message generation and solely define custom
error messages. The ConstraintValidatorContext API is modeled as fluent interface and is
best demonstrated with an example:
package com.mycompany;
import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
32
The constraint validator
if (object == null)
return true;
boolean isValid;
if (caseMode == CaseMode.UPPER) {
isValid = object.equals(object.toUpperCase());
}
else {
isValid = object.equals(object.toLowerCase());
}
if(!isValid) {
constraintContext.disableDefaultConstraintViolation();
constraintContext.buildConstraintViolationWithTemplate( "{com.mycompany.constraints.CheckCase.message}
}
return result;
}
Example 3.4, “Use of ConstraintValidatorContext to define custom error messages” shows how
you can disable the default error message generation and add a custom error message using
a specified message template. In this example the use of the ConstraintValidatorContext
results in the same error message as the default error message generation.
Tip
It is important to end each new constraint violation with addConstraintViolation.
Only after that the new constraint violation will be created.
In case you are implementing a ConstraintValidator a class level constraint it is also possible
to adjust set the property path for the created constraint violations. This is important for the case
where you validate multiple properties of the class or even traverse the object graph. A custom
property path creation could look like Example 3.5, “Adding new ConstraintViolation with custom
property path”.
33
Chapter 3. Creating custom co...
...
if(!isValid) {
constraintValidatorContext
.buildConstraintViolationWithTemplate( "{my.custom.template}" )
.addNode( "myProperty" ).addConstraintViolation();
}
return isValid;
}
Example 3.6. Defining a custom error message for the CheckCase constraint
If a validation error occurs, the validation runtime will use the default value, that we specified for
the message attribute of the @CheckCase annotation to look up the error message in this file.
package com.mycompany;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
@NotNull
private String manufacturer;
@NotNull
@Size(min = 2, max = 14)
@CheckCase(CaseMode.UPPER)
private String licensePlate;
@Min(2)
private int seatCount;
34
Using the constraint
this.manufacturer = manufacturer;
this.licensePlate = licencePlate;
this.seatCount = seatCount;
}
Finally let's demonstrate in a little test that the @CheckCase constraint is properly validated:
package com.mycompany;
import java.util.Set;
import javax.validation.ConstraintViolation;
import javax.validation.Validation;
import javax.validation.Validator;
import javax.validation.ValidatorFactory;
import org.junit.BeforeClass;
import org.junit.Test;
@BeforeClass
public static void setUp() {
ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
validator = factory.getValidator();
}
@Test
public void testLicensePlateNotUpperCase() {
Set<ConstraintViolation<Car>> constraintViolations =
validator.validate(car);
assertEquals(1, constraintViolations.size());
assertEquals(
"Case mode must be UPPER.",
constraintViolations.iterator().next().getMessage());
}
@Test
public void carIsValid() {
35
Chapter 3. Creating custom co...
Set<ConstraintViolation<Car>> constraintViolations =
validator.validate(car);
assertEquals(0, constraintViolations.size());
}
}
This problem can be tackled using compound constraints. In the following we create a new
constraint annotation @ValidLicensePlate, that comprises the constraints @NotNull, @Size and
@CheckCase:
package com.mycompany;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import javax.validation.Constraint;
import javax.validation.Payload;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
@NotNull
@Size(min = 2, max = 14)
@CheckCase(CaseMode.UPPER)
@Target( { METHOD, FIELD, ANNOTATION_TYPE })
@Retention(RUNTIME)
@Constraint(validatedBy = {})
@Documented
public @interface ValidLicensePlate {
36
Constraint composition
To do so, we just have to annotate the constraint declaration with its comprising constraints (btw.
that's exactly why we allowed annotation types as target for the @CheckCase annotation). As no
additional validation is required for the @ValidLicensePlate annotation itself, we don't declare a
validator within the @Constraint meta annotation.
Using the new compound constraint at the licensePlate field now is fully equivalent to the previous
version, where we declared the three constraints directly at the field itself:
package com.mycompany;
@ValidLicensePlate
private String licensePlate;
//...
The set of ConstraintViolations retrieved when validating a Car instance will contain an
entry for each violated composing constraint of the @ValidLicensePlate constraint. If you rather
prefer a single ConstraintViolation in case any of the composing constraints is violated, the
@ReportAsSingleViolation meta constraint can be used as follows:
//...
@ReportAsSingleViolation
public @interface ValidLicensePlate {
37
38
Chapter 4.
XML configuration
4.1. validation.xml
The key to enable XML configuration for Hibernate Validator is the file validation.xml. If this file
exists in the classpath its configuration will be applied when the ValidationFactory gets created.
Example 4.1, “validation-configuration-1.0.xsd” shows a model view of the xsd valiation.xml
has to adhere to.
<validation-config xmlns="http://jboss.org/xml/ns/javax/validation/configuration"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/configuration">
<default-provider>org.hibernate.validator.HibernateValidator</default-provider>
<message-interpolator>org.hibernate.validator.engine.ResourceBundleMessageInterpolator</
message-interpolator>
<traversable-resolver>org.hibernate.validator.engine.resolver.DefaultTraversableResolver</
traversable-resolver>
<constraint-validator-
factory>org.hibernate.validator.engine.ConstraintValidatorFactoryImpl</constraint-validator-
factory>
<constraint-mapping>/constraints-car.xml</constraint-mapping>
39
Chapter 4. XML configuration
<property name="prop1">value1</property>
<property name="prop2">value2</property>
</validation-config>
Warning
There can only be one validation.xml in the classpath. If more than one is found
an exception is thrown.
All settings shown in the validation.xml are optional and in the case of
Example 4.2, “validation.xml” show the defaults used within Hibernate Validator.
The node default-provider allows to choose the Bean Validation provider. This
is useful if there is more than one provider in the classpath. message-
interpolator, traversable-resolver and constraint-validator-factory allow to customize the
javax.validation.MessageInterpolator, javax.validation.TraversableResolver resp.
javax.validation.ConstraintValidatorFactory. The same configuration options are also
available programmatically through the javax.validation.Configuration. In fact XML
configuration will be overridden by values explicitly specified via the API. It is even possible to
ignore the XML configuration completely via Configuration.ignoreXmlConfiguration(). See
also Chapter 5, Bootstrapping.
Via the constraint-mapping you can list an arbitrary number of additional XML files containing the
actual constraint configuration. See Section 4.2, “Mapping constraints”.
Last but not least, you can specify provider specific properties via the property nodes. Hibernate
Validator does currently not make use of any custom properties.
40
Mapping constraints
41
Chapter 4. XML configuration
Example 4.4, “constraints-car.xml” shows how our classes Car and RentalCar from Example 2.15,
“Car” resp. Example 2.19, “RentalCar” could be mapped in XML.
<constraint-mappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/mapping
validation-mapping-1.0.xsd"
xmlns="http://jboss.org/xml/ns/javax/validation/mapping">
<default-package>org.hibernate.validator.quickstart</default-package>
<bean class="Car" ignore-annotations="true">
<field name="manufacturer">
<constraint annotation="javax.validation.constraints.NotNull"/>
</field>
<field name="licensePlate">
<constraint annotation="javax.validation.constraints.NotNull"/>
</field>
<field name="seatCount">
<constraint annotation="javax.validation.constraints.Min">
<element name="value">2</element>
</constraint>
</field>
<field name="driver">
<valid/>
</field>
<getter name="passedVehicleInspection" ignore-annotations="true">
<constraint annotation="javax.validation.constraints.AssertTrue">
<message>The car has to pass the vehicle inspection first</message>
<groups>
<value>CarChecks</value>
</groups>
<element name="max">10</element>
</constraint>
</getter>
</bean>
<bean class="RentalCar" ignore-annotations="true">
<class ignore-annotations="true">
<group-sequence>
<value>RentalCar</value>
<value>CarChecks</value>
</group-sequence>
</class>
</bean>
<constraint-definition annotation="org.mycompany.CheckCase" include-existing-
validator="false">
<validated-by include-existing-validators="false">
<value>org.mycompany.CheckCaseValidator</value>
</validated-by>
</constraint-definition>
</constraint-mappings>
The XML configuration is closely mirroring the programmatic API. For this reason it should suffice
to just add some comments. default-package is used for all fields where a classname is expected.
If the specified class is not fully qualified the configured default package will be used. Every
42
Mapping constraints
mapping file can then have several bean nodes, each describing the constraints on the entity with
the specified class name.
Warning
A given entity can only be configured once across all configuration files. If the same
class is configured more than once an exception is thrown.
Settings ignore-annotations to true means that constraint annotations placed on the configured
bean are ignored. The default for this value is true. ignore-annotations is also available for the
nodes class, fields and getter. If not explicitly specified on these levels the configured bean value
applies. Otherwise do the nodes class, fields and getter determine on which level the constraints
are placed (see Section 2.1, “Defining constraints”). The constraint node is then used to add
a constraint on the corresponding level. Each constraint definition must define the class via
the annotation attribute. The constraint attributes required by the Bean Validation specification
(message, groups and payload) have dedicated nodes. All other constraint specific attributes are
configured using the the element node.
The class node also allows to reconfigure the default group sequence (see Section 2.3.2,
“Redefining the default group sequence of a class”) via the group-sequence node.
Last but not least, the list of ConstraintValidators associated to a given constraint
can be altered via the constraint-definition node. The annotation attribute represents the
constraint annotation being altered. The validated-by elements represent the (ordered) list of
ConstraintValidator implementations associated to the constraint. If include-existing-validator
is set to false, validators defined on the constraint annotation are ignored. If set to true, the list
of ConstraintValidators described in XML are concatenated to the list of validators described on
the annotation.
43
44
Chapter 5.
Bootstrapping
We already seen in Section 5.1, “Configuration and ValidatorFactory” the easiest way to create
a Validator instance - Validation.buildDefaultValidatorFactory. In this chapter we have
a look at the other methods in javax.validation.Validation and how they allow to configure
several aspects of Bean Validation at bootstrapping time.
The different bootstrapping options allow, amongst other things, to bootstrap any
Bean Validation implementation on the classpath. Generally, an available provider
is discovered by the Java Service Provider [http://java.sun.com/j2se/1.3/docs/guide/jar/
jar.html#Service%20Provider] mechanism. A Bean Validation implementation includes the file
javax.validation.spi.ValidationProvider in META-INF/services. This file contains the
fully qualified classname of the ValidationProvider of the implementation. In the case of
Hibernate Validator this is org.hibernate.validator.HibernateValidator.
Note
If there are more than one Bean Validation implementation providers in the
classpath and Validation.buildDefaultValidatorFactory() is used, there
is no guarantee which provider will be chosen. To enforce the provider
Validation.byProvider() should be used.
You can also use the method Validation.byDefaultProvider() which will allow you to
configure several aspects of the created Validator instance:
45
Chapter 5. Bootstrapping
Last but not least you can ask for a Configuration object of a specific Bean Validation provider. This
is useful if you have more than one Bean Validation provider in your classpath. In this situation you
can make an explicit choice about which implementation to use. In the case of Hibernate Validator
the Validator creation looks like:
Tip
5.2. ValidationProviderResolver
In the case that the Java Service Provider mechanism does not work in your
environment or you have a special classloader setup, you are able to provide a custom
ValidationProviderResolver. An example in an OSGi environment you could plug your custom
provider resolver like seen in Example 5.4, “Providing a custom ValidationProviderResolver”.
46
MessageInterpolator
5.3. MessageInterpolator
Section 2.2.4, “Message interpolation” already discussed the default message interpolation
algorithm. If you have special requirements for your message interpolation you can provide a
custom interpolator using Configuration.messageInterpolator(). This message interpolator
will be shared by all validators generated by the ValidatorFactory created from this
Configuration(see Example 5.6, “Providing a custom MessageInterpolator”).
Tip
5.3.1. ResourceBundleLocator
A common use case is the ability to specify your own resource bundles for message
interpolation. The default MessageInterpolator implementation in Hibernate Validator is
called ResourceBundleMessageInterpolator and per default loads resource bundles via
ResourceBundle.getBundle. However, ResourceBundleMessageInterpolator also allows you
to specify a custom implementation of ResourceBundleLocator allowing you to provide your own
resource bundles. Example 5.7, “Providing a custom ResourceBundleLocator” shows an example.
47
Chapter 5. Bootstrapping
configure.messageInterpolator(new ResourceBundleMessageInterpolator(myResourceBundleLocator));
5.4. TraversableResolver
The usage of the TraversableResolver has so far not been discussed. The idea is that in
some cases, the state of a property should not be accessed. The most obvious example for
that is a lazy loaded property or association of a Java Persistence provider. Validating this lazy
property or association would mean that its state would have to be accessed triggering a load
from the database. Bean Validation controls which property can and cannot be accessed via
the TraversableResolver interface (see Example 5.8, “TraversableResolver interface”). In the
example HibernateValidatorConfiguration.
/**
* Contract determining if a property can be accessed by the Bean Validation provider
* This contract is called for each property that is being either validated or cascaded.
*
* A traversable resolver implementation must be thread-safe.
*
*/
public interface TraversableResolver {
/**
* Determine if the Bean Validation provider is allowed to reach the property state
*
* @param traversableObject object hosting <code>traversableProperty</code> or null
* if validateValue is called
* @param traversableProperty the traversable property.
* @param rootBeanType type of the root object passed to the Validator.
* @param pathToTraversableObject path from the root object to
* <code>traversableObject</code>
* (using the path specification defined by Bean Validator).
* @param elementType either <code>FIELD</code> or <code>METHOD</code>.
48
TraversableResolver
*
* @return <code>true</code> if the Bean Validation provider is allowed to
* reach the property state, <code>false</code> otherwise.
*/
boolean isReachable(Object traversableObject,
Path.Node traversableProperty,
Class<?> rootBeanType,
Path pathToTraversableObject,
ElementType elementType);
/**
* Determine if the Bean Validation provider is allowed to cascade validation on
* the bean instance returned by the property value
* marked as <code>@Valid</code>.
* Note that this method is called only if isReachable returns true for the same set of
* arguments and if the property is marked as <code>@Valid</code>
*
* @param traversableObject object hosting <code>traversableProperty</code> or null
* if validateValue is called
* @param traversableProperty the traversable property.
* @param rootBeanType type of the root object passed to the Validator.
* @param pathToTraversableObject path from the root object to
* <code>traversableObject</code>
* (using the path specification defined by Bean Validator).
* @param elementType either <code>FIELD</code> or <code>METHOD</code>.
*
* @return <code>true</code> if the Bean Validation provider is allowed to
* cascade validation, <code>false</code> otherwise.
*/
boolean isCascadable(Object traversableObject,
Path.Node traversableProperty,
Class<?> rootBeanType,
Path pathToTraversableObject,
ElementType elementType);
}
Hibernate Validator provides two TraversableResolvers out of the box which will be enabled
automatically depending on your environment. The first is the DefaultTraversableResolver
which will always return true for isReachable() and isTraversable(). The second is
the JPATraversableResolver which gets enabled when Hibernate Validator gets used in
combination with JPA 2. In case you have to provide your own resolver you can do so again using
the Configuration object as seen in Example 5.9, “Providing a custom TraversableResolver”.
49
Chapter 5. Bootstrapping
5.5. ConstraintValidatorFactory
Last but not least, there is one more configuration option to discuss, the
ConstraintValidatorFactory. The default ConstraintValidatorFactory provided by
Hibernate Validator requires a public no-arg constructor to instantiate ConstraintValidator
instances (see Section 3.1.2, “The constraint validator”). Using a custom
ConstraintValidatorFactory offers for example the possibility to use dependency injection
in constraint implementations. The configuration of the custom factory is once more via the
Configuration (Example 5.10, “Providing a custom ConstraintValidatorFactory”).
Warning
Note
50
Chapter 6.
6.1. OSGi
The Hibernate Validator jar file is conform to the OSGi specification and can be used within any
OSGi container. The classes in the following packages are exported by Hibernate Validator and
are considered part of the public API - org.hibernate.validator, org.hibernate.validator.constraints,
org.hibernate.validator.messageinterpolation and org.hibernate.validator.resourceloading.
If, for some reason, the feature needs to be disabled, set hibernate.validator.apply_to_ddl
to false. See also Table 2.2, “Built-in constraints”.
You can also limit the DDL constraint generation to a subset of the defined constraints by setting
the property org.hibernate.validator.group.ddl. The property specifies the comma-separated, fully
specified class names of the groups a constraint has to be part of in order to be considered for
DDL schema generation.
51
Chapter 6. Integration with o...
comma-separated, fully specified class names of the groups to validate. Example 6.1, “Manual
configuration of BeanValidationEvenListener” shows the default values for these properties. In
this case they could also be omitted.
Note
If the beans are not annotated with validation annotations, there is no runtime
performance cost.
In case you need to manually set the event listeners for Hibernate Core, use the following
configuration in hibernate.cfg.xml:
<hibernate-configuration>
<session-factory>
...
<property name="javax.persistence.validation.group.pre-
persist">javax.validation.groups.Default</property>
<property name="javax.persistence.validation.group.pre-
update">javax.validation.groups.Default</property>
<property name="javax.persistence.validation.group.pre-remove"></property>
...
<event type="pre-update">
<listener class="org.hibernate.cfg.beanvalidation.BeanValidationEventListener"/>
</event>
<event type="pre-insert">
<listener class="org.hibernate.cfg.beanvalidation.BeanValidationEventListener"/>
</event>
<event type="pre-delete">
<listener class="org.hibernate.cfg.beanvalidation.BeanValidationEventListener"/>
</event>
</session-factory>
</hibernate-configuration>
6.3.2. JPA
If you are using JPA 2 and Hibernate Validator is in the classpath
the JPA2 specification requires that Bean Validation gets enabled. The
properties javax.persistence.validation.group.pre-persist, javax.persistence.validation.group.pre-
update and javax.persistence.validation.group.pre-remove as described in Section 6.3.1,
52
Presentation layer validation
In a JPA 1 you will have to create and register Hibernate Validator yourself. In
case you are using Hibernate EntityManager you can add a customized version of the
BeanValidationEventListener described in Section 6.3.1, “Hibernate event-based validation”
to your project and register it manually.
<h:form>
<f:validateBean>
<h:inputText value=”#{model.property}” />
<h:selectOneRadio value=”#{model.radioProperty}” > ... </h:selectOneRadio>
<!-- other input components here -->
</f:validateBean>
</h:form>
53
54
Chapter 7.
Use of the features described in the following sections is not portable between
Bean Validation providers/implementations.
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.
The programmatic API is centered around the ConstraintMapping class which can
be found together with its supporting classes in the org.hibernate.validator.cfg package.
ConstraintMapping is the entry point to a fluent API allowing the definition of constraints.
Example 7.1, “Programmatic constraint definition” shows how the API can be used.
As you can see you can configure constraints on multiple classes and properties using method
chaining. The constraint definition classes NotNullDef, SizeDef and MinDef are helper classes
which allow to configure constraint parameters in a type-safe fashion. Definition classes exists
for all built-in constraints in the org.hibernate.validator.cfg.defs package. For a custom
constraint you can either create your own definition class extending ConstraintDef or you can
use GenericConstraintDef as seen in Example 7.2, “Programmatic constraint definition using
GenericConstraintDef”.
55
Chapter 7. Programmatic const...
mapping.type( Car.class )
.property( "licensePlate", FIELD )
.constraint( GenericConstraintDef.class )
.constraintType( CheckCase.class )
.param( "value", CaseMode.UPPER );
Last but not least, you can also define cascading constraints as well as the default group sequence
of an entity.
Once you have your ConstraintMapping 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 Example 7.4, “Creating a
Hibernate Validator specific configuration”.
HibernateValidatorConfiguration config =
Validation.byProvider( HibernateValidator.class ).configure();
config.addMapping( mapping );
ValidatorFactory factory = config.buildValidatorFactory();
Validator validator = factory.getValidator();
56
Chapter 8.
Annotation Processor
(EXPERIMENTAL)
Have you ever caught yourself by unintentionally doing things like
• annotating Strings with @Min to specify a minimum length (instead of using @Size)
Then the Hibernate Validator Annotation Processor is the right thing for you. It helps preventing
such mistakes by plugging into the build process and raising compilation errors whenever
constraint annotations are incorrectly used.
Warning
A first version of the Hibernate Validator Annotation Processor is part of
Hibernate Validator since release 4.1. It is currently still under development
and should therefore be considered as an experimental feature. Some known
issues can be found at the end of this chapter. In case any problems arise
when using the processor feel free to ask for help at the forum [https://
forum.hibernate.org/viewforum.php?f=9] or create an issue within JIRA [http://
opensource.atlassian.com/projects/hibernate/browse/HV/component/10356].
8.1. Prerequisites
The Hibernate Validator Annotation Processor is based on the "Pluggable Annotation Processing
API" as defined by JSR 269 [http://jcp.org/en/jsr/detail?id=269]. This API is part of the Java
Platform since Java 6. So be sure to use this or a later version.
8.2. Features
As of Hibernate Validator 4.1 the Hibernate Validator Annotation Processor checks that:
• constraint annotations are allowed for the type of the annotated element
• only such annotation types are annotated with constraint annotations which are constraint
annotations themselves
57
Chapter 8. Annotation Process...
8.3. Options
The behavior of the Hibernate Validator Annotation Processor can be controlled
using the processor options [http://java.sun.com/javase/6/docs/technotes/tools/windows/
javac.html#options] listed in tableTable 8.1, “Hibernate Validator Annotation Processor options”:
Option Explanation
diagnosticKind Controls how constraint problems are
reported. Must be the string representation
of one of the values from the
enum javax.tools.Diagnostic.Kind, e.g.
WARNING. A value of ERROR will cause
compilation to halt whenever the AP detects a
constraint problem. Defaults to ERROR.
verbose Controls whether detailed processing
information shall be displayed or not, useful
for debugging purposes. Must be either true
orfalse. Defaults to false.
8.4.1.1. javac
• validation-api-1.0.0.GA.jar
• hibernate-validator-annotation-processor-4.1.0.Final.jar
The following listing shows an example. The processor will be detected automatically by the
compiler and invoked during compilation.
javac src/main/java/org/hibernate/validator/ap/demo/Car.java \
58
Command line builds
-cp /path/to/validation-api-1.0.0.GA.jar \
-processorpath /path/to/validation-api-1.0.0.GA.jar:/path/to/hibernate-validator-annotation-
processor-4.1.0.Final.jar
Similar to directly working with javac, the annotation processor can be added as as compiler
argument when invoking the javac task [http://ant.apache.org/manual/CoreTasks/javac.html] for
Apache Ant [http://ant.apache.org/]:
<javac srcdir="src/main"
destdir="build/classes"
classpath="/path/to/validation-api-1.0.0.GA.jar">
<compilerarg value="-processorpath" />
<compilerarg value="/path/to/validation-api-1.0.0.GA.jar:/path/to/hibernate-validator-
annotation-processor-4.1.0.Final.jar"/>
</javac>
8.4.1.3. Maven
There are several options for integrating the annotation processor with Apache Maven [http://
maven.apache.org/]. Generally it is sufficient to add the Hibernate Validator Annotation Processor
as dependency to your project:
...
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-validator-annotation-processor</artifactId>
<version>4.1.0.Final</version>
<scope>compile</scope>
</dependency>
...
The processor will then be executed automatically by the compiler. This basically works, but
comes with the disadavantage that in some cases messages from the annotation processor are
not displayed (see MCOMPILER-66 [http://jira.codehaus.org/browse/MCOMPILER-66]).
59
Chapter 8. Annotation Process...
...
<pluginRepositories>
<pluginRepository>
<id>maven-annotation-plugin-repo</id>
<url>http://maven-annotation-plugin.googlecode.com/svn/trunk/mavenrepo</url>
</pluginRepository>
</pluginRepositories>
...
Now disable the standard annotation processing performed by the compiler plugin and configure
the annotation plugin by specifying an execution and adding the Hibernate Validator Annotation
Processor as plugin dependency (that way the AP is not visible on the project's actual classpath):
...
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.6</source>
<target>1.6</target>
<compilerArgument>-proc:none</compilerArgument>
</configuration>
</plugin>
<plugin>
<groupId>org.bsc.maven</groupId>
<artifactId>maven-processor-plugin</artifactId>
<version>1.3.4</version>
<executions>
<execution>
<id>process</id>
<goals>
<goal>process</goal>
</goals>
<phase>process-sources</phase>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-validator-annotation-processor</artifactId>
<version>4.1.0.Final</version>
<scope>compile</scope>
</dependency>
</dependencies>
</plugin>
...
60
IDE builds
8.4.2.1. Eclipse
Do the following to use the annotation processor within the Eclipse [http://www.eclipse.org/] IDE:
• Go to "Java Compiler" and make sure, that "Compiler compliance level" is set to "1.6". Otherwise
the processor won't be activated
• Go to "Java Compiler - Annotation Processing - Factory Path" and add the following JARs:
• validation-api-1.0.0.GA.jar
• hibernate-validator-annotation-processor-4.1.0.Final.jar
You now should see any annotation problems as regular error markers within the editor and in
the "Problem" view:
61
Chapter 8. Annotation Process...
The following steps must be followed to use the annotation processor within IntelliJ IDEA [http://
www.jetbrains.com/idea/] (version 9 and above):
• Choose "Enable annotation processing" and enter the following as "Processor path": /path/to/
validation-api-1.0.0.GA.jar:/path/to/hibernate-validator-annotation-processor-4.1.0.Final.jar
Rebuilding your project then should show any erronous constraint annotations:
8.4.2.3. NetBeans
Starting with version 6.9, also the NetBeans [http://www.netbeans.org/] IDE supports using
annotation processors within the IDE build. To do so, do the following:
62
Known issues
• validation-api-1.0.0.GA.jar
• hibernate-validator-annotation-processor-4.1.0.Final.jar
Any constraint annotation problems will then be marked directly within the editor:
63
Chapter 8. Annotation Process...
project can help in these situations. This seems to be an issue with the Eclipse JSR 269 API
implementation, but further investigation is required here.
64
Chapter 9.
Further reading
Last but not least, a few pointers to further information. A great source for examples is the
Bean Validation TCK which can is available for anonymous access in the Hibernate SVN
repository [http://anonsvn.jboss.org/repos/hibernate/validator/trunk]. Alternatively you can view
the tests using Hibernate's fisheye [http://fisheye.jboss.org/browse/Hibernate/beanvalidation/
trunk/validation-tck/src/main/java/org/hibernate/jsr303/tck/tests] installation. The JSR 303 [http://
jcp.org/en/jsr/detail?id=303] specification itself is also a great way to deepen your understanding
of Bean Validation resp. Hibernate Validator.
If you have any further questions to Hibernate Validator or want to share some of your use cases
have a look at the Hibernate Validator Wiki [http://community.jboss.org/en/hibernate/validator] and
the Hibernate Validator Forum [https://forum.hibernate.org/viewforum.php?f=9].
In case you would like to report a bug use Hibernate's Jira [http://opensource.atlassian.com/
projects/hibernate/browse/HV] instance. Feedback is always welcome!
65
66