Hibernate.orgCommunity Documentation
In this chapter you will learn how to declare (see Section 2.1, “Declaring bean constraints”) and validate (see Section 2.2, “Validating bean constraints”) bean constraints. Section 2.3, “Built-in constraints” provides an overview of all built-in constraints coming with Hibernate Validator.
If you are interested in applying constraints to method parameters and return values, refer to Chapter 3, Declaring and validating method constraints.
Constraints in Bean Validation are expressed via Java annotations. In this section you will learn how to enhance an object model with these annotations. There are the following three types of bean constraints:
field constraints
property constraints
class constraints
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 6, Creating custom constraints for more information.
Constraints can be expressed by annotating a field of a class. Example 2.1, “Field-level constraints” shows a field level configuration example:
Example 2.1. Field-level constraints
package org.hibernate.validator.referenceguide.chapter02.fieldlevel;
public class Car {
@NotNull
private String manufacturer;
@AssertTrue
private boolean isRegistered;
public Car(String manufacturer, boolean isRegistered) {
this.manufacturer = manufacturer;
this.isRegistered = isRegistered;
}
//getters and setters...
}
When using field-level constraints field access strategy is used to access the value to be validated. This means the validation engine directly accesses the instance variable and does not invoke the property accessor method even if such an accessor exists.
Constraints can be applied to fields of any access type (public, private etc.). Constraints on static fields are not supported, though.
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 constraints” uses the same entity as in Example 2.1, “Field-level constraints”, however, property level constraints are used.
Example 2.2. Property-level constraints
package org.hibernate.validator.referenceguide.chapter02.propertylevel;
public class Car {
private String manufacturer;
private boolean isRegistered;
public Car(String manufacturer, boolean isRegistered) {
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;
}
}
The property's getter method has to be annotated, not its setter. That way also read-only properties can be constrained which have no setter method.
When using property level constraints property access strategy is used to access the value to be validated, i.e. the validation engine accesses the state via the property accessor method.
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 the class level. In this case not a single property is subject of the validation but the complete object. Class-level constraints are useful if the validation depends on a correlation between several properties of an object.
The Car class in Example 2.3, “Class-level constraint” has the two attributes
seatCount and passengers and it
should be ensured that the list of passengers has not more entries than
seats are available. For that purpose the
@ValidPassengerCount constraint is added on the
class level. The validator of that constraint has access to the complete
Car object, allowing to compare the numbers of
seats and passengers.
Refer to Section 6.2, “Class-level constraints” to learn in detail how to implement this custom constraint.
Example 2.3. Class-level constraint
package org.hibernate.validator.referenceguide.chapter02.classlevel;
@ValidPassengerCount
public class Car {
private int seatCount;
private List<Person> passengers;
//...
}
When a class implements an interface or extends another class, all constraint annotations declared on the supertype apply in the same manner as the constraints specified on the class itself. To make things clearer let's have a look at the following example:
Example 2.4. Constraint inheritance
package org.hibernate.validator.referenceguide.chapter02.inheritance;
public class Car {
private String manufacturer;
@NotNull
public String getManufacturer() {
return manufacturer;
}
//...
}
package org.hibernate.validator.referenceguide.chapter02.inheritance;
public class RentalCar extends Car {
private String rentalStation;
@NotNull
public String getRentalStation() {
return rentalStation;
}
//...
}
Here the class RentalCar is a subclass of
Car and adds the property
rentalStation. If an instance of
RentalCar is validated, not only the
@NotNull constraint on
rentalStation is evaluated, but also the constraint
on manufacturer from the parent class.
The same would be true, if Car was not a
superclass but an interface implemented by
RentalCar.
Constraint annotations are aggregated if methods are overridden.
So if RentalCar overrode the
getManufacturer() method from
Car, any constraints annotated at the overriding
method would be evaluated in addition to the
@NotNull constraint from the superclass.
The Bean Validation API does not only allow to validate single
class instances but also complete object graphs (cascaded validation).
To do so, just annotate a field or property representing a reference to
another object with @Valid as demonstrated in
Example 2.5, “Cascaded validation”.
Example 2.5. Cascaded validation
package org.hibernate.validator.referenceguide.chapter02.objectgraph;
public class Car {
@NotNull
@Valid
private Person driver;
//...
}
package org.hibernate.validator.referenceguide.chapter02.objectgraph;
public class Person {
@NotNull
private String name;
//...
}
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.
The validation of object graphs is recursive, i.e. if a reference
marked for cascaded validation points to an object which itself has
properties annotated with @Valid, these
references will be followed up by the validation engine as well. The
validation engine will ensure that no infinite loops occur during
cascaded validation, for example if two objects hold references to each
other.
Note that null values are getting ignored
during cascaded validation.
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.6. Cascaded validation of a collection
package org.hibernate.validator.referenceguide.chapter02.objectgraph.list;
public class Car {
@NotNull
@Valid
private List<Person> passengers = new ArrayList<Person>();
//...
}
So when validating an instance of the Car
class shown in Example 2.6, “Cascaded validation of a collection”, a
ConstraintViolation will be created, if any of
the Person objects contained in the
passengers list has a null
name.
The Validator interface is the most important
object in Bean Validation. The next section shows how to obtain an
Validator instance. Afterwards you'll 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 method
Validation#buildDefaultValidatorFactory():
Example 2.7. Validation#buildDefaultValidatorFactory()
ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
Validator validator = factory.getValidator();
This bootstraps a validator in the default configuration. Refer to
Chapter 8, Bootstrapping to learn more about the
different bootstrapping methods and how to obtain a specifically
configured Validator instance.
The Validator interface contains three
methods that can be used to either validate entire entities or just
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) is used. The
topic of validation groups is discussed in detail in Chapter 5, Grouping constraints.
Use the validate() method to perform
validation of all constraints of a given bean. Example 2.8, “Using Validator#validate()” shows the validation of an
instance of the Car class from Example 2.2, “Property-level constraints” which fails to satisfy the
@NotNull constraint on the
manufacturer property. The validation call
therefore returns one ConstraintViolation
object.
Example 2.8. Using Validator#validate()
Car car = new Car( null, true );
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() you
can validate a single named property of a given object. The property
name is the JavaBeans property name.
Example 2.9. Using
Validator#validateProperty()
Car car = new Car( null, true );
Set<ConstraintViolation<Car>> constraintViolations = validator.validateProperty(
car,
"manufacturer"
);
assertEquals( 1, constraintViolations.size() );
assertEquals( "may not be null", constraintViolations.iterator().next().getMessage() );
By 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.10. Using
Validator#validateValue()
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().
Validator#validateProperty() is for
example used in the integration of Bean Validation into JSF 2 (see
Section 10.2, “JSF & Seam”) to perform a validation
of the values entered into a form before they are propagated to the
model.
Now it is time to have a closer look at what a
ConstraintViolation is. 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. The values in the "Example" column refer to Example 2.8, “Using Validator#validate()”.
Table 2.1. The various ConstraintViolation
methods
| Method | Usage | Example |
|---|---|---|
getMessage() | The interpolated error message | "may not be null" |
getMessageTemplate() | The non-interpolated error message | "{... 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 validated value from root bean | contains one node with kind
PROPERTY and name "manufacturer" |
getInvalidValue() | The value failing to pass the constraint | null |
getConstraintDescriptor() | Constraint metadata reported to fail | descriptor for @NotNull |
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(value=,
inclusive=) | BigDecimal,
BigInteger,
CharSequence,
byte, short,
int, long and the
respective wrappers of the primitive types; Additionally
supported by HV: any sub-type of
Number | Checks whether the annotated value is less than the
specified maximum, when inclusive=false.
Otherwise whether the value is less than 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(value=,
inclusive=) | BigDecimal,
BigInteger,
CharSequence,
byte, short,
int, long and the
respective wrappers of the primitive types; Additionally
supported by HV: any sub-type of
Number | Checks whether the annotated value is larger than the
specified minimum, when inclusive=false.
Otherwise whether the value is larger than 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,
CharSequence,
byte, short,
int, long and the
respective wrappers of the primitive types; Additionally
supported by HV: any sub-type of
Number | Checks whether the annoted value is a number having up to
integer digits and
fraction fractional digits | Defines 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(value=) | 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 character sequence is evaluated), any
sub-type of Number | Checks whether the annotated value is less than or equal to the specified maximum | Adds a check constraint on the column |
@Min(value=) | 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 | Adds a check constraint on the column |
@NotNull | Any type | Checks that the annotated value is not
null. | Column(s) are not nullable |
@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=) | CharSequence | Checks if the annotated string matches the regular
expression regex considering the given
flag match | None |
@Size(min=, max=) | CharSequence,
Collection, Map
and arrays | 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 has 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 |
@Email | 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. You can find more information in Chapter 6, Creating custom constraints.
Copyright © 2009 - 2013 Red Hat, Inc. & Gunnar Morling