Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
  * JBoss, Home of Professional Open Source
  * Copyright 2010, Red Hat Middleware LLC, and individual contributors
  * by the @authors tag. See the copyright.txt in the distribution for a
  * full listing of individual contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 package org.hibernate.validator.method;
 
 import java.util.Set;
 

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 javax.validation.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 java.lang.reflect.Proxy API or CDI ( "JSR 299: Contexts and Dependency Injection for the JavaTM 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 javax.validation.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.

Deprecated:
Will by replaced by equivalent functionality defined by the Bean Validation 1.1 API as of Hibernate Validator 5.
Author(s):
Gunnar Morling
public interface MethodValidator {

Validates a given parameter of a given method.

Parameters:
<T> The type hosting the invoked method.
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 javax.validation.groups.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.
															Method method,
															Object parameterValue,
															int parameterIndex,
															Class<?>... groups);

Validates all parameters of a given method.

Parameters:
<T> The type hosting the invoked method.
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 javax.validation.groups.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.
	<T> Set<MethodConstraintViolation<T>> validateAllParameters(T objectMethod methodObject[] parameterValuesClass<?>... groups);

Validates the return value of a given method.

Parameters:
<T> The type hosting the invoked method.
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 javax.validation.groups.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.
															  Method methodObject returnValueClass<?>... groups);

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.
New to GrepCode? Check out our FAQ X