Hibernate.org Community Documentation

- 上一页
- 下一页

## 第 2 章 Declaring and validating bean constraints

In this chapter you will learn how to declare (see 第 2.1 节 “Declaring bean constraints”) and validate (see 第 2.2 节 “Validating bean constraints”) bean constraints. 第 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 第 3 章 Declaring and validating method constraints.

## 2.1. Declaring bean 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 第 6 章 Creating custom constraints for more information.

### 2.1.1. Field-level constraints

Constraints can be expressed by annotating a field of a class. 例 2.1 “Field-level constraints” shows a field level configuration 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.

### 2.1.2. Property-level constraints

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. 例 2.2 “Property-level constraints” uses the same entity as in 例 2.1 “Field-level constraints”, however, property level constraints are used.

例 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.

### 2.1.3. Class-level constraints

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 例 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 第 6.2 节 “Class-level constraints” to learn in detail how to implement this custom constraint.

例 2.3. Class-level constraint

    package org.hibernate.validator.referenceguide.chapter02.classlevel;

    @ValidPassengerCount

    public class Car {

            private int seatCount;

            private List<Person> passengers;

            //...

    }

### 2.1.4. Constraint inheritance

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:

例 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.

### 2.1.5. Object graphs

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 例 2.5 “Cascaded validation”.

例 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.

例 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 例 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.

## 2.2. Validating bean constraints

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.

### 2.2.1. Obtaining a `Validator` instance

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()`:

例 2.7. Validation#buildDefaultValidatorFactory()

    ValidatorFactory factory = Validation.buildDefaultValidatorFactory();

    Validator validator = factory.getValidator();

This bootstraps a validator in the default configuration. Refer to 第 8 章 Bootstrapping to learn more about the different bootstrapping methods and how to obtain a specifically configured `Validator` instance.

### 2.2.2. Validator methods

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 第 5 章 Grouping constraints.

#### 2.2.2.1. `Validator#validate()`

Use the `validate()` method to perform validation of all constraints of a given bean. 例 2.8 “Using Validator#validate()” shows the validation of an instance of the `Car` class from 例 2.2 “Property-level constraints” which fails to satisfy the `@NotNull` constraint on the `manufacturer` property. The validation call therefore returns one `ConstraintViolation` object.

例 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() );

#### 2.2.2.2. `Validator#validateProperty()`

With help of the `validateProperty()` you can validate a single named property of a given object. The property name is the JavaBeans property name.

例 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() );

#### 2.2.2.3. `Validator#validateValue()`

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:

例 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 第 10.2 节 “JSF & Seam”) to perform a validation of the values entered into a form before they are propagated to the model.

### 2.2.3. `ConstraintViolation` methods

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. 表 2.1 “The various ConstraintViolation methods” gives an overview of these methods. The values in the "Example" column refer to 例 2.8 “Using Validator#validate()”.

表 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`

## 2.3. Built-in constraints

Hibernate Validator comprises a basic set of commonly used constraints. These are foremost the constraints defined by the Bean Validation specification (see 表 2.2 “Bean Validation constraints”). Additionally, Hibernate Validator provides useful custom constraints (see 表 2.3 “Custom constraints” and 表 2.4 “Custom country specific constraints”).

### 2.3.1. Bean Validation constraints

表 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.

表 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 表 2.2 “Bean Validation constraints” each constraint has the parameters `message`, `groups` and `payload`. This is a requirement of the Bean Validation specification.

### 2.3.2. Additional constraints

In addition to the constraints defined by the Bean Validation API Hibernate Validator provides several useful custom constraints which are listed in 表 2.3 “Custom constraints”. With one exception also these constraints apply to the field/property level, only `@ScriptAssert` is a class-level constraint.

表 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
`@EAN` | `CharSequence` | Checks that the annotated character sequence is a valid EAN barcode. `type` determines the type of barcode. The default is EAN-13. | 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`
`@LuhnCheck(``startIndex=,` `endIndex=,` `checkDigitIndex=,` `ignoreNonDigitCharacters=)` | `CharSequence` | Checks that the digits within the annotated character sequence pass the Luhn checksum algorithm (see also Luhn algorithm). `startIndex` and `endIndex` allow to only run the algorithm on the specified sub-string. `checkDigitIndex` allows to use an arbitrary digit within the character sequence as 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
`@Mod10Check(multiplier=,` `weight=, startIndex=,` `endIndex=,` `checkDigitIndex=,` `ignoreNonDigitCharacters=)` | `CharSequence` | Checks that the digits within the annotated character sequence pass the generic mod 10 checksum algorithm. `multiplier` determines the multiplier for odd numbers (defaults to 3), `weight` the weight for even numbers (defaults to 1). `startIndex` and `endIndex` allow to only run the algorithm on the specified sub-string. `checkDigitIndex` allows to use an arbitrary digit within the character sequence as 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
`@Mod11Check(threshold=,` `startIndex=, endIndex=,` `checkDigitIndex=,` `ignoreNonDigitCharacters=,` `treatCheck10As=,` `treatCheck11As=)` | `CharSequence` | Checks that the digits within the annotated character sequence pass the mod 11 checksum algorithm. `threshold` specifies the threshold for the mod11 multiplier growth; if no value is specified the multiplier will grow indefinitely. `treatCheck10As` and `treatCheck11As` specify the check digits to be used when the mod 11 checksum equals 10 or 11, respectively. Default to X and 0, respectively. `startIndex`, `endIndex` a`checkDigitIndex` and `ignoreNonDigitCharacters` carry the same semantics as in `@Mod10Check`. | 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=, additionalTagsWithAttributes=)` | `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 a predefined whitelist type can be chosen which can be refined via `additionalTags` or `additionalTagsWithAttributes`. The former allows to add tags without any attributes, whereas the latter allows to specify tags and optionally allowed attributes using the annotation `@SafeHtml.Tag`. | 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

#### 2.3.2.1. Country specific constraints

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!

表 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 第 6 章 Creating custom constraints.

版权 © 2009 - 2013 Red Hat, Inc. & Gunnar Morling

- 上一页第 1 章 Getting started
- 上一级
- 起始页
- 下一页第 3 章 Declaring and validating method constraints