The Java EE 7 Tutorial

Previous
Next

21.1 Using Bean Validation Constraints

The Bean Validation model is supported by constraints in the form of annotations placed on a field, method, or class of a JavaBeans component, such as a managed bean.

Constraints can be built in or user defined. User-defined constraints are called custom constraints. Several built-in constraints are available in the javax.validation.constraints package. Table 21-1 lists all the built-in constraints. See Creating Custom Constraints for information on creating custom constraints.

Table 21-1 Built-In Bean Validation Constraints

Constraint Description Example

@AssertFalse

The value of the field or property must be false.

 
@AssertFalse
boolean isUnsupported;

@AssertTrue

The value of the field or property must be true.

 
@AssertTrue
boolean isActive;

@DecimalMax

The value of the field or property must be a decimal value lower than or equal to the number in the value element.

 
@DecimalMax("30.00")
BigDecimal discount;

@DecimalMin

The value of the field or property must be a decimal value greater than or equal to the number in the value element.

 
@DecimalMin("5.00")
BigDecimal discount;

@Digits

The value of the field or property must be a number within a specified range. The integer element specifies the maximum integral digits for the number, and the fraction element specifies the maximum fractional digits for the number.

 
@Digits(integer=6, fraction=2)
BigDecimal price;

@Future

The value of the field or property must be a date in the future.

 
@Future
Date eventDate;

@Max

The value of the field or property must be an integer value lower than or equal to the number in the value element.

 
@Max(10)
int quantity;

@Min

The value of the field or property must be an integer value greater than or equal to the number in the value element.

 
@Min(5)
int quantity;

@NotNull

The value of the field or property must not be null.

 
@NotNull
String username;

@Null

The value of the field or property must be null.

 
@Null
String unusedString;

@Past

The value of the field or property must be a date in the past.

 
@Past
Date birthday;

@Pattern

The value of the field or property must match the regular expression defined in the regexp element.

 
@Pattern(regexp="\\(\\d{3}\\)\\d{3}-\\d{4}")
String phoneNumber;

@Size

The size of the field or property is evaluated and must match the specified boundaries. If the field or property is a String, the size of the string is evaluated. If the field or property is a Collection, the size of the Collection is evaluated. If the field or property is a Map, the size of the Map is evaluated. If the field or property is an array, the size of the array is evaluated. Use one of the optional max or min elements to specify the boundaries.

 
@Size(min=2, max=240)
String briefMessage;

In the following example, a constraint is placed on a field using the built-in @NotNull constraint:

public class Name {
    @NotNull 
    private String firstname;

    @NotNull 
    private String lastname;
    ...
}

You can also place more than one constraint on a single JavaBeans component object. For example, you can place an additional constraint for size of field on the firstname and the lastname fields:

public class Name {
    @NotNull
    @Size(min=1, max=16)
    private String firstname;

    @NotNull 
    @Size(min=1, max=16)
    private String lastname;
    ...
}

The following example shows a method with a user-defined constraint that checks for a predefined email address pattern, such as a corporate email account:

@ValidEmail 
public String getEmailAddress() {
    return emailAddress;
}

For a built-in constraint, a default implementation is available. A user-defined or custom constraint needs a validation implementation. In the preceding example, the @ValidEmail custom constraint needs an implementation class.

Any validation failures are gracefully handled and can be displayed by the h:messages tag.

Any managed bean that contains Bean Validation annotations automatically gets validation constraints placed on the fields on a JavaServer Faces application's web pages.

For more information on using validation constraints, see the following:

Previous
Next