7:43 a.m.
I am done with my work on the exception model.
Check the chapter copied in this email and the spec in general
(including javaDoc changes) at
http://hibernate.org/~emmanuel/validation/
Chapter 8. Exception model
Illegal arguments passed to the Bean Validation APIs generally lead to
a IllegalArgumentException (see JavaDoc for specific details). Other
exceptions raised by Bean Validation are or inherits from the runtime
exception javax.validation.ValidationException. Exception cases are
described in their respective sections but include (non exhaustive
list):
invalid constraint definitions (missing mandatory elements, illegal
composition cycle, illegal parameter overriding, etc)
invalid constraint declarations (ConstraintValidator implementation
matching failure, etc)
invalid group definition (circularity)
invalid Default group redefinition for classes (missing class group etc)
error when retrieving, initializing, executing ConstraintValidators
error when parsing the XML configuration or mappings
multiple XML configuration files found
missing expected provider or no default provider found
missing no-arg constructors on extension implementations described in
the XML configuration file
same entity described more than once across the XML mapping files
same property or field described more than once for a given entity in
the XML mapping files
class, field or getter declared in XML mapping files but not found
illegal XML constraint definition
illegal XML constraint declaration
exception raised either at initialization time or execution time by
any of the extension interfaces
Each of these error cases lead to a ValidationException or a subclass
of ValidationException (see following subsections).
Every (runtime) exception raised either at initialization time or
execution time by any of the extension interfaces
(ConstraintValidator, ConstraintValidatorFactory,
MessageInterpolator,TraversableResolver, ValidationProviderResolver)
is wrapped in a ValidationException.
If a constraint definition or constraint declaration is invalid for a
given class, the metadata API should raise the according exception.
8.1. Error report: ConstraintViolationException
Some frameworks or applications need to convey the results of a
validation. It is an exception case if the validation returns
constraint violation and a Java exception is raised.
Bean Validation provides a reference exception for such cases.
Frameworks and applications are encouraged to use
ConstraintViolationException as opposed to a custom exception to
increase consistency of the Java platform. The exception can be raised
directly or wrapped into the framework or application specific mother
exception.
/**
* Report the result of constraint violations
*
* @author Emmanuel Bernard
*/
public class ConstraintViolationException extends ValidationException {
/**
* Creates a constraint violation report
*
* @param message error message
* @param constraintViolations Set of ConstraintViolation
*/
public ConstraintViolationException(String message,
Set<ConstraintViolation> constraintViolations) {
[...]
}
/**
* Creates a constraint violation report
*
* @param constraintViolations Set of ConstraintViolation
*/
public ConstraintViolationException(Set<ConstraintViolation>
constraintViolations) {
[...]
}
/**
* Set of constraint violations reported during a validation
*
* @return Set of CosntraintViolation
*/
public Set<ConstraintViolation> getConstraintViolations() {
[...]
}
}
The ConstraintViolationException carries a set of ConstraintViolation.
Note
Bean Validation never raises this exception itself. Other frameworks
like Java Persistence 2 do.
8.2. Constraint definition: ConstraintDefinitionException
If a constraint definition does not respect the Bean Validation rules
or is inconsistent, a ConstraintDefinitionException is raised.
This exception can be raised during validation or when the metadata
model for the class hosting this constraint is requested.
Note
These exception cases can be determined at compile time by a tool such
as an annotation processor.
8.3. Constraint declaration: ConstraintDeclarationException and
UnexpectedTypeException
When a constraint declaration is illegal,
ConstraintDeclarationException is raised.
When the return type of a property cannot be processed for a given
constraint, an UnexpectedTypeException is raised. This problem
typically arise when either no ConstraintValidator or too many
ConstraintValidators match the return type (see Section 3.5.3,
“ConstraintValidator resolution algorithm”).
This exception can be raised during validation or when the metadata
model for the class hosting this constraint is requested.
Note
These exception cases can be determined at compile time by a tool such
as an annotation processor.
8.4. Group definition: GroupDefinitionException
When a group definition is illegal, GroupDefinitionException is
raised. This typically arises when a cyclic group dependency is
discovered.
Note
These exception cases can generally be determined at compile time by a
tool such as an annotation processor.