Table of Contents
This chapter provides a brief overview of the annotations that you'll use when defining validation for your classes. Please consult the JavaDocs for truly comprehensive information.
You'll probably use these most often. These annotations define the validation constraints themselves. These may be defined at the field or getter/setter level. Ultimately, though, all validation annotations should be defined on the same member.
Validators can categorised as either scalar validators or comparative validators. Scalar validators operate on only the annotated property. Comparative validators compare their values to some other property value.
All property validation annotations define these attributes:
| message | The validation error message. If this string is enclosed in curly braces ({}) it's assumed to be a key into the message resource bundle. Otherwise, the message is used as-is. All built-in validators have default message keys. |
| groups | Specifies the groups in which the validator belongs. Groups allow you to specify constraints that shouldn't always apply. |
All comparative validator annotations use the value attribute to specify the property being compared to. This provides a handy shortcut if you don't need to specify any other attributes, e.g. @After("dateFrom").
Table 3.1. Property validators reference
| Annotation | Description | Attribute Name | Attribute Description |
|---|---|---|---|
| After | Validates that the annotated Date or Calendar property is greater than another property. | orNull | If set true to true and the opposing value is null, then this validator will succeed. |
| ignoreTime | Ignores the time components in both dates. | ||
| AfterEqual | A specialisation of @After which allows the dates to be equal. | ||
| Before | Validates that the annotated Date or Calendar property is less than another property. | orNull | If set true to true and the opposing value is null, then this validator will succeed. |
| ignoreTime | Ignores the time components in both dates. | ||
| BeforeEqual | A specialisation of @Before which allows the dates to be equal. | ||
| DoubleRange | Validates that the annotated property is between two double-precision values. All numeric types including BigDecimal are supported. | min | The minimim value. Defaults to Double.MIN_VALUE. |
| max | The maximum value. Defaults to Double.MAX_VALUE. | ||
| inclusive | If true, then the range is inclusive (the default.) | ||
| Validates that the annotated property is a valid email address. | |||
| Equals | Validates that one property is equal to another, using the equals method. Supports nulls. | ||
| GreaterThan | Validates that the annotated member's value exceeds another property's. | orNull | If set true to true and the opposing value is null, then this validator will succeed. |
| orNull | If set true to true and the opposing value is null, then this validator will succeed. | ||
| GreaterThanEqual | A specialisation of @GreaterThan which allows the values to be equal. | ||
| Length | Validates the length of the annotation string property. | min | The minimim length. Defaults to 0. |
| max | The maximum length. Defaults to Integer.MAX_VALUE. | ||
| LessThan | Validates that the annotated member's value is less than another property's. | orNull | If set true to true and the opposing value is null, then this validator will succeed. |
| LessThanEqual | A specialisation of @LessThan which allows the values to be equal. | ||
| LongRange | Validates that the annotated property is between two integral values. All integral types are supported. | min | The minimim value. Defaults to Long.MIN_VALUE. |
| max | The maximum value. Defaults to Long.MAX_VALUE. | ||
| inclusive | If true, then the range is inclusive (the default.) | ||
| Matches | Validates that the annotated property matches a given regular expression. | value | The regular expression pattern. |
| Required | Marks a property as being required (non-null.) | ||
| Same | Validates that the annotated Date or Calendar property is equal to another property. | ignoreTime | Ignores the time components in both dates. |
| Size | Validates the length of the annotated array, Map or Collection. | min | The minimim length. Defaults to 0. |
| max | The maximum length. Defaults to Integer.MAX_VALUE. | ||
| orNull | If set and the property is null, then this validator will succeed. | ||
| UseColumnValidation | A special EJB 3.0 and Seam-specific validator that re-uses the length, nullable scale and precision attributes of the EJB 3.0 @Column validator. This will also use the @ManyToOne and/or @JoinColumn annotations, or, if used inside an @Embedded class, the @Column annotation on the applicable @AttributeOverride. |
Vetoers are conditional validation annotations that may cause validation to be aborted (vetoed) if the condition is not met. They are always checked before validators are.
Similar to Property Validators, vetoers support a groups annotation.
Vetoers all work by testing some other property defined by the value attribute. For example, @IfTrue("hasAddress") will only perform the validation on the annotated element if the hasAddress value is true
Table 3.2. Property vetoers reference
| Annotation | Description |
|---|---|
| IfFalse | Validates the annotated property only if another (boolean) property is false. |
| IfTrue | Validates the annotated property only if another (boolean) property is true. |
| IfNotNull | Validates the annotated property only if another property is non-null. |
| IfNull | Validates the annotated property only if another property is null. |
Many of the built-in validators' error messages include the property name or names to make the messages more readable. Often property names aren't good enough. With the @FieldDesc annotation you can define friendly field names.
Property validation will often be all that you need, but sometimes it's necessary to perform validation on an entire object. The Bean Validator framework supports validation classes and method for this purpose.
Both the annotations discussed in this section -- @InstanceValidationClass and @LocalValidato support these common attributes:
| groups | Specifies the groups in which the instance validator belongs. |
| abortOnError | Should the validator abort if it encounters an error? |
| order | An instance of the enumerated type com.sadalbari.validator.core.annotation.InstanceValidationOrder. Defines whether the validator runs before or after the bean's properties are validated. |
This is the recommended way to implement validation classes. Define a class that implements the com.sadalbari.validator.core.InstanceValidator interface. Then define a type-level @InstanceValidationClass annotation on the target class. The value attribute specifies the class of the instance validator implementation.
You can define multiple validators on a class using the @InstanceValidationClasses annotation.
It is also possible to define instance methods that perform validation using the @LocalValidator annotation.
This annotation may only be defined on an a method that returns an array of com.sadalbari.validator.core.InstanceValidationError. See the JavaDocs of that class for more details.
These are meta-annotations that are used to control the Bean Validator's behaviour and to manage the EJB 3.0 and Seam integration processes.
Table 3.3. Miscellanerous annotation reference
| Annotation | Description | Attribute Name | Attribute Description |
|---|---|---|---|
| Valid | Seam-specific annotation that causes Seam to apply the Bean Validator interceptor to an EJB 3.0 session bean. | ||
| ValidateChild | Marks a property for recursive validation. | prefixes | Specifies zero or more PrefixBeanNames that provide aliases for nested properties. |
| ValidationEvaluator | Defines an instance of com.sadalbari.validator.core.ValidationEvalauator that is used to determine whether a given validated child (see above) should actually be validated. This is very useful, for example, when certain trees of objects are re-used in more than one place, but not all use cases define the same objects as being required. | value | Specifies the implementation of ValidationEvaluator to use. |
| Validated | Optional annotation that defines a class as being validated. You normally only need to use this to change the property access strategy. | value | The AccessStrategy to use. Either property (i.e. getter/setter -- the default) or field-level access is available. |
| ValidateParam | Marks the annotated parameter for recursive validation. | prefixes | Specifies zero or more PrefixBeanNames that provide aliases for nested properties. |
| PrefixBeanName | Specifies that any property validation errors errors belonging to the bean specified by the dot-notation bean attribute should be prefixed with the prefix, with a period as the delimiter. | bean | The dot-notation property name to alias, relative to the annotated element. |
| prefix | The prefix to use for the property name. | ||
| ValidationGroup | Specifies that the annotated method will invoke bean validation for the specified group only. Used by both the EJB 3.0 and Seam interceptors. This is useful if, for example, there is different validation for adding or updating entities, and there are different methods for those two operations. | value | The validation group to execute. |