/*
 * Bean Validation API
 *
 * License: Apache License, Version 2.0
 * See the license.txt file in the root directory or <http://www.apache.org/licenses/LICENSE-2.0>.
 */
package javax.validation.metadata;

import java.util.Set;

import javax.validation.Valid;

Describes a constrained Java Bean and the constraints associated to it. All objects returned by the methods of this descriptor (and associated objects including ConstraintDescriptors) are immutable. 
Author:
Emmanuel Bernard, Gunnar Morling/**
 * Describes a constrained Java Bean and the constraints associated to it. All
 * objects returned by the methods of this descriptor (and associated objects
 * including {@link ConstraintDescriptor}s) are immutable.
 *
 * @author Emmanuel Bernard
 * @author Gunnar Morling
 */
public interface BeanDescriptor extends ElementDescriptor {

	
Returns true if the bean involves validation: 

    
a constraint is hosted on the bean itself
    
a constraint is hosted on one of the bean properties
    
or a bean property is marked for cascaded validation (Valid)


Constrained methods and constructors are ignored.
Returns:
true if the bean involves validation, false otherwise/**
	 * Returns {@code true} if the bean involves validation:
	 * <ul>
	 *     <li>a constraint is hosted on the bean itself</li>
	 *     <li>a constraint is hosted on one of the bean properties</li>
	 *     <li>or a bean property is marked for cascaded validation ({@link Valid})</li>
	 * </ul>
	 * <p>
	 * Constrained methods and constructors are ignored.
	 *
	 * @return {@code true} if the bean involves validation, {@code false} otherwise
	 */
	boolean isBeanConstrained();

	
Returns the property descriptor for a given property.
 Returns null if the property does not exist or has no constraint nor is marked as cascaded (see getConstrainedProperties()) Properties of super types are considered. 
Params:
propertyName – property evaluated
Throws:
IllegalArgumentException – if propertyName is null
Returns:
the property descriptor for a given property/**
	 * Returns the property descriptor for a given property.
	 * <p>
	 * Returns {@code null} if the property does not exist or has no
	 * constraint nor is marked as cascaded (see {@link #getConstrainedProperties()})
	 * Properties of super types are considered.
	 *
	 * @param propertyName property evaluated
	 * @return the property descriptor for a given property
	 * @throws IllegalArgumentException if {@code propertyName} is {@code null}
	 */
	PropertyDescriptor getConstraintsForProperty(String propertyName);

	
Returns a set of property descriptors having at least one constraint defined or marked as cascaded (Valid). 

If no property matches, an empty set is returned.
Properties of super types are considered.
Returns:
the set of PropertyDescriptors for the constraint properties; if there are no constraint properties, the empty set is returned/**
	 * Returns a set of property descriptors having at least one constraint defined
	 * or marked as cascaded ({@link Valid}).
	 * <p>
	 * If no property matches, an empty set is returned.
	 * Properties of super types are considered.
	 *
	 * @return the set of {@link PropertyDescriptor}s for the constraint properties; if
	 *         there are no constraint properties, the empty set is returned
	 */
	Set<PropertyDescriptor> getConstrainedProperties();

	
Returns a method descriptor for the given method.
 Returns null if no method with the given name and parameter types exists or the specified method neither has parameter or return value constraints nor a parameter or return value marked for cascaded validation. Methods of super types are considered. 
Params:
methodName – the name of the method
parameterTypes – the parameter types of the method
Throws:
IllegalArgumentException – if methodName is null
Returns:
a method descriptor for the given method
Since:
1.1/**
	 * Returns a method descriptor for the given method.
	 * <p>
	 * Returns {@code null} if no method with the given name and parameter types
	 * exists or the specified method neither has parameter or return value constraints nor a
	 * parameter or return value marked for cascaded validation.
	 * Methods of super types are considered.
	 *
	 * @param methodName the name of the method
	 * @param parameterTypes the parameter types of the method
	 * @return a method descriptor for the given method
	 * @throws IllegalArgumentException if {@code methodName} is {@code null}
	 *
	 * @since 1.1
	 */
	MethodDescriptor getConstraintsForMethod(String methodName, Class<?>... parameterTypes);

	
Returns a set with descriptors for the constrained methods of the bean
represented by this descriptor.

Constrained methods have at least one parameter or return value constraint
or at least one parameter or return value marked for cascaded validation.
Methods of super types are considered.

Only methods matching the given method type(s) are considered.
Params:
methodType – method type to consider
methodTypes – remaining optional method types to consider
Returns:
a set with descriptors for the constrained methods of this bean; will be empty if this bean has no constrained methods of the considered method type(s) but never null
Since:
1.1/**
	 * Returns a set with descriptors for the constrained methods of the bean
	 * represented by this descriptor.
	 * <p>
	 * Constrained methods have at least one parameter or return value constraint
	 * or at least one parameter or return value marked for cascaded validation.
	 * Methods of super types are considered.
	 * <p>
	 * Only methods matching the given method type(s) are considered.
	 *
	 * @param methodType method type to consider
	 * @param methodTypes remaining optional method types to consider
	 * @return a set with descriptors for the constrained methods of this bean;
	 *         will be empty if this bean has no constrained methods of the considered
	 *         method type(s) but never {@code null}
	 *
	 * @since 1.1
	 */
	Set<MethodDescriptor> getConstrainedMethods(MethodType methodType,
												MethodType... methodTypes);

	
Returns a constructor descriptor for the given constructor.
 Returns null if no constructor with the given parameter types exists or the specified constructor neither has parameter or return value constraints nor a parameter or return value marked for cascaded validation. 
Params:
parameterTypes – the parameter types of the constructor
Returns:
a constructor descriptor for the given constructor
Since:
1.1/**
	 * Returns a constructor descriptor for the given constructor.
	 * <p>
	 * Returns {@code null} if no constructor with the given parameter types
	 * exists or the specified constructor neither has parameter or return value
	 * constraints nor a parameter or return value marked for cascaded
	 * validation.
	 *
	 * @param parameterTypes the parameter types of the constructor
	 * @return a constructor descriptor for the given constructor
	 *
	 * @since 1.1
	 */
	ConstructorDescriptor getConstraintsForConstructor(Class<?>... parameterTypes);

	
Returns a set with descriptors for the constrained constructors of the
bean represented by this descriptor.

Constrained constructors have at least one parameter or return value constraint
or at least one parameter or return value marked for cascaded validation.
Returns:
a set with descriptors for the constrained constructor of this bean; will be empty if this bean has no constrained constructor but never null
Since:
1.1/**
	 * Returns a set with descriptors for the constrained constructors of the
	 * bean represented by this descriptor.
	 * <p>
	 * Constrained constructors have at least one parameter or return value constraint
	 * or at least one parameter or return value marked for cascaded validation.
	 *
	 * @return a set with descriptors for the constrained constructor of this
	 *         bean; will be empty if this bean has no constrained constructor
	 *         but never {@code null}
	 *
	 * @since 1.1
	 */
	Set<ConstructorDescriptor> getConstrainedConstructors();
}