[hibernate-dev] [Bean Validation] exception model

[Emmanuel Bernard]

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/hibernate-dev/attachments/20090225/a83c4e08/attachment.html