Hibernate.orgCommunity Documentation
In this chapter we will see in more detail how to use Hibernate Validator to validate constraints for a given entity model. We will also learn which default constraints the Bean Validation specification provides and which additional constraints are only provided by Hibernate Validator. Let's start with how to add constraints to an entity.
Constraints in Bean Validation are expressed via Java annotations. In this section we show how to annotate an object model with these annotations. We have to differentiate between three different type of constraint annotations - field-, property-, and class-level annotations.
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.
Constraints can be expressed by annotating a field of a class. Example 2.1, “Field level constraint” shows a field level configuration example:
Example 2.1. Field level constraint
package com.mycompany;
import javax.validation.constraints.NotNull;
public class Car {
@NotNull
private String manufacturer;
@AssertTrue
private boolean isRegistered;
public Car(String manufacturer, boolean isRegistered) {
super();
this.manufacturer = manufacturer;
this.isRegistered = isRegistered;
}
}
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.
The access type (private, protected or public) does not matter.
Static fields and properties cannot be validated.
When validating byte code enhanced objects property level constraints should be used, because the byte code enhancing library won't be able to determine a field access via reflection.
If your model class adheres to the JavaBeans standard, it is also possible to annotate the properties of a bean class instead of its fields. Example 2.2, “Property level constraint” uses the same entity as in Example 2.1, “Field level constraint”, however, property level constraints are used.
The property's getter method has to be annotated, not its setter.
Example 2.2. Property level constraint
package com.mycompany;
import javax.validation.constraints.AssertTrue;
import javax.validation.constraints.NotNull;
public class Car {
private String manufacturer;
private boolean isRegistered;
public Car(String manufacturer, boolean isRegistered) {
super();
this.manufacturer = manufacturer;
this.isRegistered = isRegistered;
}
@NotNull
public String getManufacturer() {
return manufacturer;
}
public void setManufacturer(String manufacturer) {
this.manufacturer = manufacturer;
}
@AssertTrue
public boolean isRegistered() {
return isRegistered;
}
public void setRegistered(boolean isRegistered) {
this.isRegistered = 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. One advantage of annotating properties instead of fields is that the constraints become part of the constrained type's API that way and users are aware of the existing constraints without having to examine the type's implementation.
It is recommended to stick either to field or property annotations 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.
Last but not least, a constraint can also be placed on class
level. When a constraint annotation is placed on this level the class
instance itself passed to the
ConstraintValidator. Class level constraints are
useful if it is necessary to inspect more than a single property of the
class to validate it or if a correlation between different state
variables has to be evaluated. In Example 2.3, “Class level constraint”
we add the property passengers to the class
Car. We also add the constraint
PassengerCount on the class level. We will later
see how we can actually create this custom constraint (see Chapter 3, Creating custom constraints). For now it is enough to know
that PassengerCount will ensure that there cannot
be more passengers in a car than there are seats.
Example 2.3. Class level constraint
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;
@NotNull
@Size(min = 2, max = 14)
private String licensePlate;
@Min(2)
private int seatCount;
private List<Person> passengers;
public Car(String manufacturer, String licencePlate, int seatCount) {
this.manufacturer = manufacturer;
this.licensePlate = licencePlate;
this.seatCount = seatCount;
}
//getters and setters ...
}
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:
Example 2.4. Constraint inheritance using RentalCar
package com.mycompany;
import javax.validation.constraints.NotNull;
public class RentalCar extends Car {
private String rentalStation;
public RentalCar(String manufacturer, String rentalStation) {
super(manufacturer);
this.rentalStation = rentalStation;
}
@NotNull
public String getRentalStation() {
return rentalStation;
}
public void setRentalStation(String rentalStation) {
this.rentalStation = rentalStation;
}
}
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.
The Bean Validation API does not only allow to validate single
class instances but also complete object graphs. To do so, just annotate
a field or property representing a reference to another object with
@Valid. If the parent object is validated, all
referenced objects annotated with @Valid will be
validated as well (as will be their children etc.). See Example 2.6, “Adding a driver to the car”.
Example 2.5. Class Person
package com.mycompany;
import javax.validation.constraints.NotNull;
public class Person {
@NotNull
private String name;
public Person(String name) {
super();
this.name = name;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
}
Example 2.6. Adding a driver to the car
package com.mycompany;
import javax.validation.Valid;
import javax.validation.constraints.NotNull;
public class Car {
@NotNull
@Valid
private Person driver;
public Car(Person driver) {
this.driver = driver;
}
//getters and setters ...
}
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.lang.Iterable
(especially Collection,
List and Set)
implement java.util.Map
can be annotated with @Valid, which will
cause each contained element to be validated, when the parent object is
validated.
Example 2.7. Car with a list of passengers
package com.mycompany;
import java.util.ArrayList;
import java.util.List;
import javax.validation.Valid;
import javax.validation.constraints.NotNull;
public class Car {
@NotNull
@Valid
private List<Person> passengers = new ArrayList<Person>();
public Car(List<Person> passengers) {
this.passengers = passengers;
}
//getters and setters ...
}
If a Car instance is validated, a
ConstraintValidation will be created, if any of
the Person objects contained in the
passengers list has a null name.
null values are getting ignored when
validating object graphs.
The Validator interface is the main entry
point to Bean Validation. In Section 5.1, “Configuration and
ValidatorFactory”
we will first show how to obtain an Validator
instance. Afterwards we will learn how to use the different methods of the
Validator interface.
The first step towards validating an entity instance is to get
hold of a Validator instance. The road to this
instance leads via the Validation class and a
ValidatorFactory. The easiest way is to use the
static
Validation.buildDefaultValidatorFactory()
method:
Example 2.8. Validation.buildDefaultValidatorFactory()
ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
Validator validator = factory.getValidator();
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.
The Validator interface contains three
methods that can be used to either validate entire entities or just a
single properties of the entity.
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”
Use the validate() method to perform
validation of all constraints of a given entity instance (see Example 2.9, “Usage of
Validator.validate()” ).
Example 2.9. Usage of
Validator.validate()
ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
Validator validator = factory.getValidator();
Car car = new Car(null);
Set<ConstraintViolation<Car>> constraintViolations = validator.validate(car);
assertEquals(1, constraintViolations.size());
assertEquals("may not be null", constraintViolations.iterator().next().getMessage());
With help of the validateProperty() a
single named property of a given object can be validated. The property
name is the JavaBeans property name.
Example 2.10. Usage of
Validator.validateProperty()
Validator validator = Validation.buildDefaultValidatorFactory().getValidator();
Car car = new Car(null);
Set<ConstraintViolation<Car>> constraintViolations = validator.validateProperty(car, "manufacturer");
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 7.4, “Presentation layer validation”).
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:
Example 2.11. Usage of
Validator.validateValue()
Validator validator = Validation.buildDefaultValidatorFactory().getValidator();
Set<ConstraintViolation<Car>> constraintViolations = validator.validateValue(Car.class, "manufacturer", null);
assertEquals(1, constraintViolations.size());
assertEquals("may not be null", constraintViolations.iterator().next().getMessage());
@Valid is not honored by
validateProperty() or
validateValue().
Now it is time to have a closer look at what a
ConstraintViolation. Using the different methods
of ConstraintViolation a lot of useful
information about the cause of the validation failure can be determined.
Table 2.1, “The various ConstraintViolation
methods” gives an overview of these
methods:
Table 2.1. The various ConstraintViolation
methods
| Method | Usage | Example (referring to Example 2.9, “Usage of Validator.validate()”) |
|---|---|---|
getMessage() | The interpolated error message. | may not be null |
getMessageTemplate() | The non-interpolated error message. | {javax.validation.constraints.NotNull.message} |
getRootBean() | The root bean being validated. | car |
getRootBeanClass() | The class of the root bean being validated. | Car.class |
getLeafBean() | If a bean constraint, the bean instance the constraint is applied on. If a property constraint, the bean instance hosting the property the constraint is applied on. | car |
getPropertyPath() | The property path to the value from root bean. | |
getInvalidValue() | The value failing to pass the constraint. | passengers |
getConstraintDescriptor() | Constraint metadata reported to fail. |
As we will see in Chapter 3, Creating custom constraints
each constraint definition must define a default message descriptor.
This message can be overridden at declaration time using the
message attribute of the constraint. You can
see this in Example 2.13, “Driver”. This message descriptors
get interpolated when a constraint validation fails using the configured
MessageInterpolator. The interpolator will try to
resolve any message parameters, meaning string literals enclosed in
braces. In order to resolve these parameters Hibernate Validator's
default MessageInterpolator first recursively
resolves parameters against a custom
ResourceBundle called
ValidationMessages.properties at the root of the
classpath (It is up to you to create this file). If no further
replacements are possible against the custom bundle the default
ResourceBundle under
/org/hibernate/validator/ValidationMessages.properties
gets evaluated. If a replacement occurs against the default bundle the
algorithm looks again at the custom bundle (and so on). Once no further
replacements against these two resource bundles are possible remaining
parameters are getting resolved against the attributes of the constraint
to be validated.
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:
\{ is considered as the literal {
\} is considered as the literal }
\\ is considered as the literal \
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.
Groups allow you to restrict the set of constraints applied during
validation. This makes for example wizard like validation possible where
in each step only a specified subset of constraints get validated. The
groups targeted are passed as var-args parameters to
validate,
validateProperty and
validateValue. Let's have a look at an extended
Car with Driver example.
First we have the class Person (Example 2.12, “Person”) which has a @NotNull
constraint on name. Since no group is
specified for this annotation its default group is
javax.validation.groups.Default.
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.
Example 2.12. Person
public class Person {
@NotNull
private String name;
public Person(String name) {
this.name = name;
}
// getters and setters ...
}
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.
Example 2.13. Driver
public class Driver extends Person {
@Min(value = 18, message = "You have to be 18 to drive a car", groups = DriverChecks.class)
public int age;
@AssertTrue(message = "You first have to pass the driving test", groups = DriverChecks.class)
public boolean hasDrivingLicense;
public Driver(String name) {
super( name );
}
public void passedDrivingTest(boolean b) {
hasDrivingLicense = b;
}
public int getAge() {
return age;
}
public void setAge(int age) {
this.age = age;
}
}
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.
Example 2.15. Car
public class Car {
@NotNull
private String manufacturer;
@NotNull
@Size(min = 2, max = 14)
private String licensePlate;
@Min(2)
private int seatCount;
@AssertTrue(message = "The car has to pass the vehicle inspection first", groups = CarChecks.class)
private boolean passedVehicleInspection;
@Valid
private Driver driver;
public Car(String manufacturer, String licencePlate, int seatCount) {
this.manufacturer = manufacturer;
this.licensePlate = licencePlate;
this.seatCount = seatCount;
}
}
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.
Example 2.16. Drive away
public class GroupTest {
private static Validator validator;
@BeforeClass
public static void setUp() {
ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
validator = factory.getValidator();
}
@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() );
// but has it passed the vehicle inspection?
constraintViolations = validator.validate( car, CarChecks.class );
assertEquals( 1, constraintViolations.size() );
assertEquals("The car has to pass the vehicle inspection first", constraintViolations.iterator().next().getMessage());
// let's go to the vehicle inspection
car.setPassedVehicleInspection( true );
assertEquals( 0, validator.validate( car ).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() );
// ok, John passes the test
john.passedDrivingTest( true );
assertEquals( 0, validator.validate( car, DriverChecks.class ).size() );
// just checking that everything is in order now
assertEquals( 0, validator.validate( car, Default.class, CarChecks.class, DriverChecks.class ).size() );
}
}
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,
regardless of which groups they belong to. In some situations, however,
it is useful to control the order constraints are evaluated. 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 order one would define a new interface and annotate it
with @GroupSequence defining the order in which
the groups have to be validated.
If at least one constraint fails in a sequenced group none of the constraints of the following groups in the sequence get validated.
Example 2.17. Interface with @GroupSequence
@GroupSequence({Default.class, CarChecks.class, DriverChecks.class})
public interface OrderedChecks {
}
Groups defining a sequence and groups composing a sequence
must not be involved in a cyclic dependency either directly or
indirectly, either through cascaded sequence definition or group
inheritance. If a group containing such a circularity is evaluated,
a GroupDefinitionException is raised.
The usage of the new sequence could then look like in Example 2.18, “Usage of a group sequence”.
Example 2.18. Usage of a group sequence
@Test
public void testOrderedChecks() {
Car car = new Car( "Morris", "DD-AB-123", 2 );
car.setPassedVehicleInspection( true );
Driver john = new Driver( "John Doe" );
john.setAge( 18 );
john.passedDrivingTest( true );
car.setDriver( john );
assertEquals( 0, validator.validate( car, OrderedChecks.class ).size() );
}
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 given class, add a
@GroupSequence annotation to the class. The
defined groups in the annotation express the sequence of groups that
substitute Default for this class. Example 2.19, “RentalCar with @GroupSequence” introduces a new class
RentalCar with a redefined default group. With
this definition you can evaluate the constraints belonging to
RentalChecks, CarChecks
and RentalCar by just requesting the
Default group as seen in Example 2.20, “RentalCar with redefined default group”.
Example 2.19. RentalCar with @GroupSequence
@GroupSequence({ RentalChecks.class, CarChecks.class, RentalCar.class })
public class RentalCar extends Car {
@AssertFalse(message = "The car is currently rented out", groups = RentalChecks.class)
private boolean rented;
public RentalCar(String manufacturer, String licencePlate, int seatCount) {
super( manufacturer, licencePlate, seatCount );
}
public boolean isRented() {
return rented;
}
public void setRented(boolean rented) {
this.rented = rented;
}
}
Example 2.20. RentalCar with redefined default group
/**
* Validating the default group leads to validation on the default group sequence of {@code RentalCar}.
*/
@Test
public void carIsRented() {
RentalCar rentalCar = new RentalCar( "Morris", "DD-AB-123", 2 );
rentalCar.setPassedVehicleInspection( true );
rentalCar.setRented( true );
Set<ConstraintViolation<RentalCar>> constraintViolations = validator.validate( rentalCar );
assertEquals( 1, constraintViolations.size() );
assertEquals(
"Wrong message",
"The car is currently rented out",
constraintViolations.iterator().next().getMessage()
);
rentalCar.setRented( false );
constraintViolations = validator.validate( rentalCar );
assertEquals( 0, constraintViolations.size() );
}
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
has to be added!
The Default group sequence overriding
is local to the class it is defined on and is not propagated to the
associated objects. This means in particular that adding
DriverChecks to the default group sequence of
RentalCar would not have any effects. Only
the group Default will be propagated to the
driver association when validation a rental car instance.
The @javax.validation.GroupSequence
annotation is a standardized Bean Validation annotation. As seen in
the previous section it allows you to statically redefine the default
group sequence for a class. Hibernate Validator also offers a custom,
non standardized annotation -
org.hibernate.validator.group.GroupSequenceProvider
- which allows for dynamic redefinition of the default
group sequence. Using the rental car scenario again, one could
dynamically add the CarChecks as seen in Example 2.21, “RentalCar with @GroupSequenceProvider” and Example , “DefaultGroupSequenceProvider implementation”.
Example 2.21. RentalCar with @GroupSequenceProvider
@GroupSequenceProvider(RentalCarGroupSequenceProvider.class)
public class RentalCar extends Car {
@AssertFalse(message = "The car is currently rented out", groups = RentalChecks.class)
private boolean rented;
public RentalCar(String manufacturer, String licencePlate, int seatCount) {
super( manufacturer, licencePlate, seatCount );
}
public boolean isRented() {
return rented;
}
public void setRented(boolean rented) {
this.rented = rented;
}
}
Example . DefaultGroupSequenceProvider implementation
public class RentalCarGroupSequenceProvider implements DefaultGroupSequenceProvider<RentalCar> {
public List<Class<?>> getValidationGroups(RentalCar car) {
List<Class<?>> defaultGroupSequence = new ArrayList<Class<?>>();
defaultGroupSequence.add( RentalCar.class );
if ( car != null && !car.isRented() ) {
defaultGroupSequence.add( CarChecks.class );
}
return defaultGroupSequence;
}
}
Hibernate Validator comprises a basic set of commonly used constraints. These are foremost the constraints defined by the Bean Validation specification (see Table 2.2, “Bean Validation constraints”). Additionally, Hibernate Validator provides useful custom constraints (see Table 2.3, “Custom constraints” and Table 2.4, “Custom country specific constraints”).
Table 2.2, “Bean Validation constraints” shows purpose and supported data types of all constraints specified in the Bean Validation API. All these constraints apply to the field/property level, there are no class-level constraints defined in the Bean Validation specification. If you are using the Hibernate object-relational mapper, some of the constraints are taken into account when creating the DDL for your model (see column "Hibernate metadata impact").
Hibernate Validator allows some constraints to be applied to
more data types than required by the Bean Validation specification
(e.g. @Max can be applied to Strings). Relying
on this feature can impact portability of your application between
Bean Validation providers.
Table 2.2. Bean Validation constraints
| Annotation | Supported data types | Use | Hibernate metadata impact |
|---|---|---|---|
| @AssertFalse | Boolean,
boolean | Checks that the annotated element is
false. | none |
| @AssertTrue | Boolean,
boolean | Checks that the annotated element is
true. | none |
| @DecimalMax | BigDecimal,
BigInteger,
String, byte,
short, int,
long and the respective wrappers of the
primitive types. Additionally supported by HV: any sub-type of
Number and
CharSequence. | The annotated element must be a number whose value must
be lower or equal to the specified maximum. The parameter value
is the string representation of the max value according to the
BigDecimal string representation. | none |
| @DecimalMin | BigDecimal,
BigInteger,
String, byte,
short, int,
long and the respective wrappers of the
primitive types. Additionally supported by HV: any sub-type of
Number and
CharSequence. | The annotated element must be a number whose value must
be higher or equal to the specified minimum. The parameter value
is the string representation of the min value according to the
BigDecimal string representation. | none |
| @Digits(integer=, fraction=) | BigDecimal,
BigInteger,
String, byte,
short, int,
long and the respective wrappers of the
primitive types. Additionally supported by HV: any sub-type of
Number and
CharSequence. | Checks whether the annoted value is a number having up to
integer digits and
fraction fractional digits. | Define column precision and scale. |
| @Future | java.util.Date,
java.util.Calendar; Additionally
supported by HV, if the Joda Time
date/time API is on the class path: any implementations of
ReadablePartial and
ReadableInstant. | Checks whether the annotated date is in the future. | none |
| @Max | BigDecimal,
BigInteger, byte,
short, int,
long and the respective wrappers of the
primitive types. Additionally supported by HV: any sub-type
ofCharSequence (the numeric value
represented by the character sequence is evaluated), any
sub-type of Number. | Checks whether the annotated value is less than or equal to the specified maximum. | Add a check constraint on the column. |
| @Min | BigDecimal,
BigInteger, byte,
short, int,
long and the respective wrappers of the
primitive types. Additionally supported by HV: any sub-type of
CharSequence (the numeric value
represented by the char sequence is evaluated), any sub-type of
Number. | Checks whether the annotated value is higher than or equal to the specified minimum. | Add a check constraint on the column. |
| @NotNull | Any type | Checks that the annotated value is not
null. | Column(s) are not null. |
| @Null | Any type | Checks that the annotated value is
null. | none |
| @Past | java.util.Date,
java.util.Calendar; Additionally
supported by HV, if the Joda Time
date/time API is on the class path: any implementations of
ReadablePartial and
ReadableInstant. | Checks whether the annotated date is in the past. | none |
| @Pattern(regex=, flag=) | String. Additionally supported by
HV: any sub-type of CharSequence. | Checks if the annotated string matches the regular
expression regex considering the given
flag match. | none |
| @Size(min=, max=) | String,
Collection, Map
and arrays. Additionally supported by HV:
any sub-type of CharSequence. | Checks if the annotated element's size is between min and max (inclusive). | Column length will be set to max. |
| @Valid | Any non-primitive type | Performs validation recursively on the associated object. If the object is a collection or an array, the elements are validated recursively. If the object is a map, the value elements are validated recursively. | none |
On top of the parameters indicated in Table 2.2, “Bean Validation constraints” each constraint supports the
parameters message,
groups and payload. This
is a requirement of the Bean Validation specification.
In addition to the constraints defined by the Bean Validation API Hibernate Validator provides several useful custom constraints which are listed in Table 2.3, “Custom constraints”. With one exception also these constraints apply to the field/property level, only @ScriptAssert is a class-level constraint.
Table 2.3. Custom constraints
| Annotation | Supported data types | Use | Hibernate metadata impact |
|---|---|---|---|
| @CreditCardNumber | CharSequence | Checks that the annotated character sequence passes the Luhn checksum test. Note, this validation aims to check for user mistakes, not credit card validity! See also Anatomy of Credit Card Numbers. | none |
CharSequence | Checks whether the specified character sequence is a
valid email address. The optional parameters
regexp and flags
allow to specify an additional regular expression (including
regular expression flags) which the email must match. | none | |
| @Length(min=, max=) | CharSequence | Validates that the annotated character sequence is
between min and
max included. | Column length will be set to max. |
| @ModCheck(modType=, multiplier=, startIndex=, endIndex=, checkDigitPosition=, ignoreNonDigitCharacters=) | CharSequence | Checks that the digits within the annotated character
sequence pass the mod 10 or mod 11 checksum algorithm.
modType is used to select the modulo type
and the multiplier determines the algorithm
specific multiplier (see also Luhn
algorithm). startIndex and
endIndex allow to only run the modulo
algorithm on the specified sub-string.
checkDigitPosition allows to use an
arbitrary digit within the character sequence to be the check
digit. If not specified it is assumed that the check digit is
part of the specified range. Last but not least,
ignoreNonDigitCharacters allows to ignore
non digit characters. | none |
| @NotBlank | CharSequence | Checks that the annotated character sequence is not null and the trimmed length is greater than 0. The difference to @NotEmpty is that this constraint can only be applied on strings and that trailing whitespaces are ignored. | none |
| @NotEmpty | CharSequence,
Collection, Map
and arrays | Checks whether the annotated element is not
null nor empty. | none |
| @Range(min=, max=) | BigDecimal,
BigInteger,
CharSequence,
byte, short,
int, long and the
respective wrappers of the primitive types | Checks whether the annotated value lies between (inclusive) the specified minimum and maximum. | none |
| @SafeHtml(whitelistType=, additionalTags=) | CharSequence | Checks whether the annotated value contains potentially
malicious fragments such as <script/>. In
order to use this constraint, the jsoup library must be part of
the class path. With the whitelistType
attribute predefined whitelist types can be chosen. You can also
specify additional html tags for the whitelist with the
additionalTags attribute. | none |
| @ScriptAssert(lang=, script=, alias=) | Any type | Checks whether the given script can successfully be evaluated against the annotated element. In order to use this constraint, an implementation of the Java Scripting API as defined by JSR 223 ("Scripting for the JavaTM Platform") must part of the class path. The expressions to be evaluated can be written in any scripting or expression language, for which a JSR 223 compatible engine can be found in the class path. | none |
| @URL(protocol=, host=, port=, regexp=, flags=) | CharSequence | Checks if the annotated character sequence is a valid URL
according to RFC2396. If any of the optional parameters
protocol, host or
port are specified, the corresponding URL
fragments must match the specified values. The optional
parameters regexp and
flags allow to specify an additional
regular expression (including regular expression flags) which
the URL must match. | none |
Hibernate Validator offers also some country specific constraints, e.g. for the validation of social security numbers.
If you have to implement a country specific constraint, consider making it a contribution to Hibernate Validator!
Table 2.4. Custom country specific constraints
| Annotation | Supported data types | Use | Country | Hibernate metadata impact |
|---|---|---|---|---|
| @CNPJ | CharSequence | Checks that the annotated character sequence represents a Brazilian corporate tax payer registry number (Cadastro de Pessoa Juríeddica) | Brazil | none |
| @CPF | CharSequence | Checks that the annotated character sequence represents a Brazilian individual taxpayer registry number (Cadastro de Pessoa Fídsica). | Brazil | none |
| @TituloEleitoral | CharSequence | Checks that the annotated character sequence represents a Brazilian voter ID card number (Título Eleitoral). | Brazil | none |
In some cases neither the Bean Validation constraints nor the custom constraints provided by Hibernate Validator will fulfill your requirements. In this case you can easily write your own constraint. We will discuss this in Chapter 3, Creating custom constraints.
Copyright © 2009 - 2011 Red Hat, Inc. & Gunnar Morling