org.hibernate.validator.method

Interface MethodValidator

All Known Implementing Classes:

ValidatorImpl

public interface MethodValidator

Provides an API for method-level constraint validation, based on JSR 303: Bean Validation, Appendix C ("Proposal for method-level validation").

The purpose of this API is to provide a facility for the Programming by Contract approach to program design based on the concepts defined by the Bean Validation API. More specifically this means that any Bean Validation constraints (built-in as well as custom 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).

These constraints may be declared directly on a method's parameters and/or return values. Alternatively, by annotating method parameters/return values with the special Valid annotation a recursive validation of those parameters/return values against the constraints defined on their types can be triggered. Consider for instance the method declaration

 @NotNull
 @Valid
 Customer findCustomerByName(@NotNull @Size(min = 5) String name) {
        // ...
 }
 

Here, the validation engine will check for the following pre- and postconditions (provided the method validation is triggered automatically by some integration layer, see below):

• The name parameter is guaranteed to be not null and at least 5 characters long. In particular it is not necessary for the implementor of this method to perform these checks manually.
• It is guaranteed that the call yields a non-null object, which itself is valid according to all the bean validation constraints declared on its type. In particular it is not necessary for the caller to perform these checks manually.

This service only deals with the actual validation of method parameters/return values itself, but not with the invocation of such a validation. It is expected that this invocation is triggered by an integration layer using AOP or similar method interception facilities such as the JDK's Proxy API or CDI ( "JSR 299: Contexts and Dependency Injection for the Java^TM EE platform" ).

Such an integration layer would typically intercept each method call to be validated, validate the call's parameters, proceed with the method invocation and finally validate the invocation's return value. If any of the validation steps yields a non-empty set of constraint violations the integration layer would typically throw a MethodConstraintViolationException wrapping these violations which in turn guarantees that the call flow only arrives at the method's implementation respectively call site if all pre- respectively postconditions are fulfilled.

MethodValidator instances are obtained by unwrapping a Validator object:

 Validator validator = ...;
 MethodValidator methodValidator = validator.unwrap(MethodValidator.class);
 

Method level validation is (currently) a proprietary feature of Hibernate Validator (HV), so the unwrapped Validator instance must be HV's implementation. In case there are multiple Bean Validation implementations on the classpath, this can be done be explicitly choosing HV as validation provider:

 MethodValidator methodValidator = Validation.byProvider(HibernateValidator.class)
        .configure()
        .buildValidatorFactory()
        .getValidator()
        .unwrap(MethodValidator.class);
 

If not stated otherwise, none of this interface's methods allow null as parameter value.

Author:

Gunnar Morling

Method Summary

Methods

Modifier and Type	Method and Description
TypeDescriptor	getConstraintsForType(Class<?> clazz) Returns a descriptor providing access to constraint-related meta data for the given type.
<T> Set<MethodConstraintViolation<T>>	validateAllParameters(T object, Method method, Object[] parameterValues, Class<?>... groups) Validates all parameters of a given method.
<T> Set<MethodConstraintViolation<T>>	validateParameter(T object, Method method, Object parameterValue, int parameterIndex, Class<?>... groups) Validates a given parameter of a given method.
<T> Set<MethodConstraintViolation<T>>	validateReturnValue(T object, Method method, Object returnValue, Class<?>... groups) Validates the return value of a given method.

Method Detail

validateParameter

<T> Set<MethodConstraintViolation<T>> validateParameter(T object,
                                                      Method method,
                                                      Object parameterValue,
                                                      int parameterIndex,
                                                      Class<?>... groups)

Validates a given parameter of a given method.

Type Parameters:

T - The type hosting the invoked method.

Parameters:

object - The object on which the given method was invoked.

method - The invoked method for which the given parameter shall be validated.

parameterValue - The value provided by the caller for the given method.

parameterIndex - The index of the parameter to be validated within the given method's parameter array.

groups - A - potentially empty - number of validation groups for which the validation shall be performed. The @link Default group will be validated if no group is given.

Returns:

A set with the constraint violations caused by this validation. Will be empty, of no error occurs, but never null.

validateAllParameters

<T> Set<MethodConstraintViolation<T>> validateAllParameters(T object,
                                                          Method method,
                                                          Object[] parameterValues,
                                                          Class<?>... groups)

Validates all parameters of a given method.

Type Parameters:

T - The type hosting the invoked method.

Parameters:

object - The object on which the given method was invoked.

method - The invoked method for which the given parameter shall be validated.

parameterValues - The values provided by the caller for the given method's parameters.

groups - A - potentially empty - number of validation groups for which the validation shall be performed. The @link Default group will be validated if no group is given.

Returns:

A set with the constraint violations caused by this validation. Will be empty, of no error occurs, but never null.

validateReturnValue

<T> Set<MethodConstraintViolation<T>> validateReturnValue(T object,
                                                        Method method,
                                                        Object returnValue,
                                                        Class<?>... groups)

Validates the return value of a given method.

Type Parameters:

T - The type hosting the invoked method.

Parameters:

object - The object on which the given method was invoked.

method - The invoked method for which the given return value shall be validated.

returnValue - The value returned by the invoked method.

groups - A - potentially empty - number of validation groups for which the validation shall be performed. The @link Default group will be validated if no group is given.

Returns:

A set with the constraint violations caused by this validation. Will be empty, of no error occurs, but never null.

getConstraintsForType

TypeDescriptor getConstraintsForType(Class<?> clazz)

Returns a descriptor providing access to constraint-related meta data for the given type.

Parameters:

clazz - The type of interest.

Returns:

A descriptor for the given type, will never be null.