Chapter 80. Method Validation

Hibernate Validator provides several advanced validation features and related functionality which go beyond what is defined by JSR 303 ("Bean Validation API"). One of these additional features is a facility for the validation of method parameters and return values. With that API a style of program design known as "Programming by Contract" can be implemented using the concepts defined by the Bean Validation API.

This means that any Bean Validation constraints can be used to describe

any preconditions that must be met before a method may legally be invoked (by annotating method parameters with constraints) and
any postconditions that are guaranteed after a method invocation returns (by annotating methods)

To give an example listing Example 80.1, “Exemplary repository with constraint annotations” shows a fictional repository class which retrieves customer objects for a given name. Constraint annotations are used here to express the following pre-/postconditions:

The value for the name parameter may not be null and must be at least three characters long
The method may never return null and each Customer object contained in the returned set is valid with respect to all constraints it hosts

Example 80.1. Exemplary repository with constraint annotations

@AutoValidating

public class CustomerRepository {


    @NotNull @Valid Set<Customer> findCustomersByName(@NotNull @Size(min=3) String name);


}

Hibernate Validator itself provides only an API for validating method parameters and return values, but it does not trigger this validation itself.

This is where Seam Validation comes into play. Seam Validation provides a so called business method interceptor which intercepts client invocations of a method and performs a validation of the method arguments before as well as a validation of the return value after the actual method invocation.

To control for which types such a validation shall be performed, Seam Validation provides an interceptor binding, @AutoValidating. If this annotation is declared on a given type an automatic validation of each invocation of any this type's methods will be performed.

If either during the parameter or the return value validation at least one constraint violation is detected (e.g. because findCustomersByName() from listing Example 80.1, “Exemplary repository with constraint annotations” was invoked with a String only two characters long), a MethodConstraintViolationException is thrown. That way it is ensured that all parameter constraints are fulfilled when the call flow comes to the method implementation (so it is not necessary to perform any parameter null checks manually for instance) and all return value constraints are fulfilled when the call flow returns to the caller of the method.

The exception thrown by Seam Validation (which would typically be written to a log file) gives a clear overview what went wrong during method invocation:

Example 80.2. Output of MethodConstraintViolationException

org.hibernate.validator.MethodConstraintViolationException: 1 constraint violation(s) occurred during method invocation.
Method: public java.lang.Set com.mycompany.service.CustomerRepository.findCustomersByName(java.lang.String)
Argument values: [B]
Constraint violations: 
  (1) Kind: PARAMETER
      parameter index: 0
      message: size must be between 3 and 2147483647
      root bean: com.mycompany.service.org$jboss$weld$bean-flat-ManagedBean-class_com$mycompany$service$$CustomerRepository_$$_WeldSubclass@3f72c47b
      property path: CustomerRepository#findCustomersByName(arg0)
      constraint: @javax.validation.constraints.Size(message={javax.validation.constraints.Size.message}, min=3, max=2147483647, payload=[], groups=[])

To make use of Seam Validation's validation interceptor it has to be registered in your component's beans.xml descriptor as shown in listing Example 80.3, “Registering the validation interceptor in beans.xml”:

Example 80.3. Registering the validation interceptor in beans.xml


<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

   xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">



   <interceptors>

      <class>org.jboss.seam.validation.ValidationInterceptor</class>

   </interceptors>

</beans>

It is recommended that you consult the Hibernate Validator reference guide to learn more about the method validation feature in general or for instance the rules that apply for constraining methods in inheritance hierarchies in particular.