JSR-349: Bean Validation TCK Coverage

Applying a constraint annotation to an incompatible type will raise an UnexpectedTypeException.

If a constraint definition is not valid, a ConstraintDefinitionException is raised either at validation time or when the metadata is requested.

A constraint definition may have attributes that are specified at the time the constraint is applied to a JavaBean.

Annotation elements starting with valid are not allowed

Every constraint annotation must define a message element of type String.

Every constraint annotation must define a groups element that specifies the processing groups with which the constraint declaration is associated.

The type of the groups parameter is Class<?>[].

The default value must be an empty array.

If no group is specified when declaring the constraint on an element, the Default group is considered declared.

Constraint annotations must define a payload element that specifies the payload with which the the constraint declaration is associated.

The default value must be an empty array.

Each attachable payload extends Payload.

The bean validation provider treats regular annotations (annotations not annotated by @Constraint) whose value element has a return type of an array of constraint annotations in a special way. Each element in the value array are processed by the Bean Validation implementation as regular constraint annotations.

More formally, each constraint annotation hosted on a constraint annotation is applied to the target element and this is done recursively.

Note that the main annotation and its constraint validation implementation is also applied.

By default, each failing constraint generates an error report.

Groups from the main constraint annotation are inherited by the composing annotations.

Any groups definition on a composing annotation is ignored.

Any payload definition on a composing annotation is ignored.

The property type upon which composed constraint is placed must be compatible with all constraints (composing and composed).

More specifically, if a composed constraint is marked as @ReportAsSingleViolation, the evaluation of the composing constraints stops at the first failing constraint and the error report corresponding to the composed constraint is generated and returned.

Composing annotations can define the value of message and custom attributes (excluding groups and payload) but these are fixed in the composed constraint definition.

It is possible to override attributes and messages defined on a composing annotation. An attribute from the main annotation is used to override one or more attributes of the composing annotations. Such an attribute is annotated with the @OverridesAttribute annotation or its multivalued equivalent @OverridesAttribute.List.

The types of the overridden and overriding attributes must be identical.

A composing constraint can itself be a composed constraint. In this case, attribute values are overridden recursively according to the described rules.

If a constraint is used more than once as a composing constraint, the multi value constraints model as described in 3.2 is used.

To select a specific composing constraint, OverridesAttribute.constraintIndex is used. It represents the constraint index in the value array.

If index is undefined, the single constraint declaration is targeted.

If the composition is invalid, e.g. infinitely recursive composition wrong attribute overriding a single attribute mapped to more than one source attribute A composing and composed constraint marked as different constraint types (i.e., generic with @Constraint and cross-parameter with @CrossParameterConstraint) etc. a ConstraintDefinitionException is raised either at validation time or when the metadata is requested.

A constraint validation implementation performs the validation of a given constraint annotation for a given type.

The implementation classes are specified by the validatedBy element of the @Constraint respectively @CrossParameterConstraint annotation that decorates the constraint definition.

If A is a cross-parameter constraint annotation type, T must resolve to Object[] in order to have the array of parameter values passed to the isValid() method.

The initialize method is called by the Bean validation provider prior to any use of the constraint implementation.

The isValid method is evaluated by the Bean Validation provider each time a given value is validated.

If the property is of an unanticipated type, an UnexpectedTypeException is raised.

If an exception occurs either in the initialize or isValid method, the runtime exception is wrapped into a ValidationException by the Bean Validation engine.

By default, each invalid constraint leads to the generation of one error object represented by a ConstraintViolation object. This object is built from the default constraint message template as defined by the constraint declaration and the context in which the constraint declaration is placed (bean, property, attribute, method or constructor parameter, method or constructor return value).

The ConstraintValidatorContext methods let the constraint implementation disable the default ConstraintViolation generation and create one or more custom ones.

The non-interpolated message passed as a parameter is used to build the ConstraintViolation message (the message interpolation operation is applied to it).

By default, the Path exposed on the ConstraintViolation represents the path to the bean, property, parameter or return value hosting the constraint (see 5.2 for more information).

You can point it to a subpath of this default path by using the constraint violation builder fluent API.

If disableDefaultConstraintViolation is called, no custom error is added (using the error builder) and if the constraint is not valid, a ValidationException is raised.

The default ConstraintValidatorFactory provided by the Bean Validation provider implementation uses the public no-arg constructor of the ConstraintValidator class.

If an exception occurs in the factory while retrieving the ConstraintValidator instance, the runtime exception is wrapped in a ValidationException.

If the instance returned by the factory is null, a ValidationException is raised.

Properties to be validated must follow the method signature conventions for JavaBeans read properties, as defined by the JavaBeans specification. These properties are commonly referred as getters.

Constraints can be applied to interfaces and superclasses.

The target of an annotation definition can be a field, property, or type, provided that: the constraint definition supports the specified target (java.lang.annotation.Target) one of the ConstraintValidators declared on the constraint supports the declared type of the target (see 4.6.4).

Constraint declarations can be applied to a class or an interface.

Constraint declarations can be applied on both fields and properties for the same object type.

The same constraint should however not be duplicated between a field and its associated property (the constraint validation would be applied twice).

When a field is annotated with a constraint declaration, field access strategy is used to access the state validated by such constraint.

When a property is annotated with a constraint declaration, property access strategy is used to access the state validated by such constraint.

The fields or methods visibility are not constrained.

Consider the situation where bean X contains a field of type Y. By annotating field Y with the @Valid annotation, the Validator will validate Y (and its properties) when X is validated.

The exact type Z of the value contained in the field declared of type Y (subclass, implementation) is determined at runtime. The constraint definitions of Z are used.

Any object implementing java.lang.Iterable is supported.

Arrays of objects

java.util.Collection

java.util.Set

java.util.List

java.util.Map

For Map, the value of each Map.Entry is validated (the key is not validated).

Like regular references, its type is determined at runtime and the constraint definitions for this particular type are used.

The @Valid annotation is applied recursively.

A constraint declaration can be placed on an interface.

For a given class, constraint declarations held on superclasses as well as interfaces are evaluated by the Bean Validation provider.

If no group is explicitly declared, a constraint belongs to the Default group.

Groups are represented by interfaces.

A constraint can belong to one or more groups.

During the validation call, one or more groups are validated. All the constraints belonging to this set of group is evaluated on the object graph.

A group may inherit one or more groups by using interface inheritance.

For a given interface Z, constraints marked as belonging to the group Z (i.e. where the annotation element groups contains the interface Z) or any of the super interfaces of Z (inherited groups) are considered part of the group Z.

Each group in a group sequence must be processed sequentially in the order defined by @GroupSequence.value when the group defined as a sequence is requested.

Note that a group member of a sequence can itself be composed of several groups via inheritance or sequence definition. In this case, each composed group must respect the sequence order as well.

If one of the groups processed in the sequence generates one or more constraint violations, the groups following in the sequence must not be processed.

Groups defining a sequence and groups composing a sequence must not be involved in a cyclic dependency: either directly or indirectly either through cascaded sequence definitions or group inheritance

If a group containing such a circularity is evaluated, a GroupDefinitionException is raised.

To define a group as a sequence, the interface must be annotated with the @GroupSequence annotation.

A given constraint can belong to two or more groups ordered by a sequence. In this case, the constraint is evaluated as part of the first group and ignored in the subsequent group(s).

To redefine Default for a class, place a @GroupSequence annotation on the class; this sequence expresses the sequence of groups that does substitute Default for this class.

A sequence defined on a class A (i.e. redefining the Default groups for the class) must contain the group A.

If a @GroupSequence redefining the Default group for a class A does not contain the group A, a GroupDefinitionException is raised when the class is validated or when its metadata is requested.

Every constraint hosted on an interface Z and part of the Default group (implicitly or explicitly) belongs to the group Z.

@ConvertGroup and @ConvertGroup.List can be used everywhere @Valid can be used (associations, method/constructor parameters and return value). If these annotations are used without @Valid, a ConstraintDeclarationException is raised.

If the group expected to be passed to the nested element validation is defined as the from attribute of a @ConvertGroup annotation, the group used to effectively validate the nested element is the corresponding group defined in the to attribute.

Rules are not executed recursively.

It is not legal to have more than one conversion rule containing the same from value. In this case, a ConstraintDeclarationException is raised.

Like regular constraint declarations, the from attribute cannot refer to a group sequence. A ConstraintDeclarationException is raised in this situation.

The to attribute can. The group sequence will then be expanded before validating the associated object.

@ConvertGroup and @ConvertGroup.List can only be placed where @Valid is present to ensure proper respect of the Liskov substitution principle

Likewise, if a sub type overrides/implements a method originally defined in several parallel types of the hierarchy (e.g. two interfaces not extending each other, or a class and an interface not implemented by said class) and if that method's return value has been marked for cascading validation in one of the parallel types, no group conversion rule may be declared for that method's return value in the parallel types of the hierarchy.

If any of these rules is violated, a ConstraintDeclarationException is raised by default as defined in 4.5.5.

If X has no @GroupSequence annotation, the group Default contains the following constraints: every constraint in the group X if X has a direct superclass Y, every constraint in the group Default of Y

If X does have a @GroupSequence annotation, the group Default contains every constraint belonging to every group declared by the @GroupSequence annotation.

Constrained methods must be non-static.

Parameter constraints are declared by putting constraint annotations on method or constructor parameters.

Cross-parameter constraints are declared by putting cross-parameter constraint annotations on methods or constructors

Cross parameters constraints are validated at the same time as parameter constraints.

A conforming Bean Validation implementation provides a default ParameterNameProvider implementation which returns parameter names in the form argPARAMETERINDEX, where PARAMETERINDEX starts at 0 for the first parameter, e.g. arg0, arg1 etc.

If an exception occurs during invocation of the getParameterNames() methods, this exception is wrapped into a ValidationException by the Bean Validation engine.

Return value constraints are declared by putting constraint annotations directly on a method or constructor.

Similar to normal bean validation, the @Valid annotation is used to declare that a cascaded validation of the given method parameters or return values shall be performed by the Bean Validation provider. When marked, the parameter or return value is considered a bean object to validate.

Null arguments and null return values are ignored

The validation is recursive; that is, if validated parameter or return value objects have references marked with @Valid themselves, these references will also be validated

In sub types (be it sub classes/interfaces or interface implementations) no parameter constraints must be declared on overridden or implemented methods, nor may parameters be marked for cascaded validation. This would pose a strengthening of preconditions to be fulfilled by the caller.

If a sub type overrides/implements a method originally defined in several parallel types of the hierarchy (e.g. two interfaces not extending each other, or a class and an interface not implemented by said class) no parameter constraints may be declared for that method at all nor parameters be marked for cascaded validation. This again is to avoid an unexpected strengthening of preconditions to be fulfilled by the caller.

In sub types (be it sub classes/interfaces or interface implementations) return value constraints may be declared on overridden or implemented methods and the return value may be marked for cascaded validation. Upon validation, all return value constraints of the method in question are validated, wherever they are declared in the hierarchy; This only poses possibly a strengthening but no weakening of the method's postconditions guaranteed to the caller.

One must not mark a method return value for cascaded validation more than once in a line of a class hierarchy. In other words, overriding methods on sub types (be it sub classes/interfaces or interface implementations) cannot mark the return value for cascaded validation if the return value has already been marked on the overridden method of the super type or interface.

The above rules do not apply when validating constructor constraints as constructors do not override one another. Parameter and return value constraints can be applied to any constructor in the type hierarchy, but only the constraints defined directly on the validated constructor are evaluated.

Note that this implies that a given validation constraint will not be processed more than once per validation.

The @Valid annotation on a given association (i.e. object reference or collection, array, Iterable of objects), dictates the Bean Validator implementation to apply recursively the Bean Validation routine on (each of) the associated object(s).

This mechanism is recursive: an associated object can itself contain cascaded references.

Null references are ignored.

To prevent infinite loops, the Bean Validation implementation must ignore the cascading operation if the associated object instance has already been validated in the current navigation path (starting from the root object).

@Valid is an orthogonal concept to the notion of group. If two groups are in sequence, the first group must pass for all associated objects before the second group is evaluated.

For a given group, the validation routine applied to validate parameters of a method or constructor is expected to execute the following constraint validations in no particular order

For a given group, the validation routine applied to validate the return value of a method or constructor is expected to execute the following constraint validations in no particular order

Note that this implies that a given validation constraint will not be processed more than once per validation.

Unless ordered by group sequences, groups can be validated in no particular order.

isReachable is called for every property about to be accessed either for validation or for cascading.

isCascadable is called for every property about to be cascaded (i.e. marked as @Valid).

isCascadable for a given property is only called if isReachable returns true. In other words, isReachable is always called before isCascadable for a given property.

The Bean Validation provider must not access the state of a property, nor validate its constraints if the property is not traversable. A property is traversable if TraversableResolver returns true for this property.

If an exception occurs when the TraversableResolver is called, the exception is wrapped into a ValidationException.

If the constraint declaration is hosted on a class or an interface, the targeted type is the class or the interface.

If the constraint is hosted on a class attribute, the type of the attribute is the targeted type.

If the constraint is hosted on a getter, the return type of the getter is the targeted type.

The ConstraintValidator chosen to validate a declared type T is the one where the type supported by the ConstraintValidator is a supertype of T and where there is no other ConstraintValidator whose supported type is a supertype of T and not a supertype of the chosen ConstraintValidator supported type.

If no ConstraintValidator compliant with T is found amongst the ConstraintValidators listed by the constraint A, an UnexpectedTypeException is raised.

If more than one maximally specific ConstraintValidator is found, an UnexpectedTypeException is raised.

<T> Set<ConstraintViolation<T>> validate(T object, Class<?>... groups) is used to validate a given object.

An IllegalArgumentException is thrown when null is passed for the object parameter or the varargs groups parameter.

A Set containing all ConstraintViolation objects representing the failing constraints is returned, an empty Set is returned otherwise.

<T> Set<ConstraintViolation<T>> validateProperty(T object, String propertyName, Class<?>... groups) validates a given field or property of an object.

An IllegalArgumentException is thrown when validateProperty is called and object is null or propertyName is null empty or invalid or null is passed to the varargs groups parameter.

The property name is the JavaBeans property name (as defined by the JavaBeans Introspector class).

@Valid is not honored by this method.

<T> Set<ConstraintViolation<T>> validateValue(Class<T> beanType, String propertyName, Object value, Class<?>... groups) validates the property referenced by propertyName present on beanType or any of its superclasses, if the property value were value.

An IllegalArgumentException is thrown when validateValue is called and object is null or propertyName is null empty or invalid or null is passed to the varargs groups parameter.

@Valid is not honored by this method.

If some unrecoverable failure happens during validation, a ValidationException is raised.

<T> Set<ConstraintViolation<T>> validateParameters(T object, Method method, Object[] parameterValues, Class<?>... groups) validates the arguments (as given in parameterValues) for the parameters of a given method (identified by method).

A set containing all ConstraintViolation objects representing the failing constraints is returned, an empty set is returned if no constraint violation occurred.

An IllegalArgumentException will be thrown if null is passed for any of the parameters.

<T> Set<ConstraintViolation<T>> validateReturnValue(T object, Method method, Object returnValue, Class<?>... groups) validates the return value (specified by returnValue) of a given method (identified by method).

A set containing all ConstraintViolation objects representing the failing constraints is returned, an empty set is returned if no constraint violation occurred.

An IllegalArgumentException will be thrown if null is passed for any of the parameters object, method and groups.

<T> Set<ConstraintViolation<T>> validateConstructorParameters(Constructor<T> constructor, Object[] parameterValues, Class<?>... groups) validates the arguments (as given in parameterValues) for the parameters of a given constructor (identified by constructor).

A set containing all ConstraintViolation objects representing the failing constraints is returned, an empty set is returned if no constraint violation occurred.

An IllegalArgumentException will be thrown if null is passed for any of the parameters.

<T> Set<ConstraintViolation<T>> validateConstructorReturnValue(Constructor<T> constructor, T createdObject, Class<?>... groups) validates the object (specified by createdObject) of a given constructor (identified by constructor).

A set containing all ConstraintViolation objects representing the failing constraints is returned, an empty set is returned if no constraint violation occurred.

An IllegalArgumentException will be thrown if null is passed for any of the parameters.

All constraints belonging to the targeted group are applied during the 4.6.

If no group is passed, the Default group is assumed.

The getMessage method returns the interpolated (localized) message for the failing constraint

The getMessageTemplate method returns the non-interpolated error message

The getRootBean method returns the root object being validated that led to the failing constraint

The getInvalidValue method returns the value (field, property, method/constructor parameter, method/constructor return value or validated object) being passed to isValid.

For a cross-parameter constraint, an Object[] representing the method/constructor invocation arguments is returned.

getConstraintDescriptor provides access to the failing constraint metadata

The getPropertyPath method returns the Path object representing the navigation path from the root object to the failing object.

The runtime type is considered, not the static type. For example if a property is declared Collection<String> but its runtime type is ArrayList<String>, the property is considered an ArrayList<String>.

If the failing object is the root object, a Node with name set to null is added to the Path. The Kind of the node's ElementDescriptor is Kind.BEAN.

A Node object whose name equals the name of the association property (field name or Java Bean property name) is added to Path. The Kind of the node's ElementDescriptor is Kind.PROPERTY.

If the association is a List or an array, the following Node object added contains the index value in getIndex.

If the association is a Map, the following Node object added (representing a given map entry) contains the key value in getKey

For all Iterable or Map, the following Node object added is marked as inIterable (isInIterable)

For a property level constraint (field and getter) a Node object is added to Path whose name equals the name of the property (field name or Java Bean property name). The Kind of the node's ElementDescriptor is Kind.PROPERTY. the property path is considered complete

For a class level constraint: a Node object is added to Path whose name is null. The Kind of the node's ElementDescriptor is Kind.BEAN. the property path is considered complete

A Node object is added to the Path which represents the validated method or constructor. The name of the node equals the validated method or constructor, the Kind of the node's ElementDescriptor is Kind.METHOD respectively Kind.CONSTRUCTOR.

A Node object is added to the Path which represents the validated parameter or return value. In the parameter case, the name of the node equals the parameter name as determined by the current parameter name provider (see 4.5.2.2). In the return value case, the name of the node is null. The Kind of the node's ElementDescriptor is Kind.PARAMETER respectively Kind.RETURN_VALUE.

The property path is considered complete

A Node object is added to the Path which represents the concerned method or constructor. The name of the node equals the concerned method or constructor, the Kind of the node's ElementDescriptor is Kind.METHOD respectively Kind.CONSTRUCTOR.

A Node object is added to the Path which represents the traversed parameter or return value. In the parameter case, the name of the node equals the parameter name as determined by the current parameter name provider. In the return value case, the name of the node is null. The Kind of the node's ElementDescriptor is Kind.PARAMETER respectively Kind.RETURN_VALUE.

If the parameter/return value is a List or an array, the following Node object added contains the index value in getIndex.

If the parameter/return value is a Map, the following Node object added (representing a given map entry) contains the key value ingetKey.

For all Iterable or Map, the following Node object added is marked as inIterable (isInIterable)

Every conforming Bean Validation implementation includes a default message interpolator which has to comply with

Each constraint defines a message descriptor via its message property.

Every constraint definition shall define a default message descriptor for that constraint.

Messages can be overridden at constraint declaration time by setting the message property on the constraint.

The message descriptor is a string literal and may contain one or more message parameters or expressions. Message parameters and expressions are string literals enclosed in {} or ${} respectively.

\{ is considered as the literal { instead of being considered as the beginning of a message parameter

\} is considered as the literal } instead of being considered as the end of a message parameter

\\ is considered as the literal \ instead of being considered as the escaping character

Message parameters are extracted from the message string and used as keys to search the ResourceBundle named ValidationMessages

Step 1 is applied recursively until no replacement is performed

Message parameters are extracted from the message string and used as keys to search the Bean Validation provider's built-in ResourceBundle using the defined locale (see 5.3.1.2). If a property is found, the message parameter is replaced with the property value in the message string.

Message parameters are extracted from the message string. Those matching the name of an attribute of the constraint are replaced by the value of that attribute in the constraint declaration. Parameter interpolation has precedence over message expressions. For example for the message descriptor ${value}, trying to evaluate {value} as message parameter has precedence over evaluating ${value} as message expression.

If the locale is passed explicitly to the interpolator method via interpolate(String, Context, Locale), this provided instance is used.

Otherwise, the default Locale as provided by Locale.getDefault() is used.

It is possible to override the MessageInterpolator implementation for a given Validator instance by invoking ValidatorFactory.usingContext().messageInterpolator(messageInterpolator).getValidator().

A bootstrap implementation must be able to bootstrap any Bean Validation provider implementation.

getMessageInterpolator() returns the MessageInterpolator instance configured during the initialization of the ValidatorFactory.

getParameterNameProvider() returns the ParameterNameProvider instance configured during the initialization of the ValidatorFactory.

The MessageInterpolator, the TraversableResolver, the ConstraintValidatorFactory or the ParameterNameProvider passed to the ValidatorContext are used instead of the ValidatorFactory's MessageInterpolator, TraversableResolver, ConstraintValidatorFactory or ParameterNameProvider instances.

Configuration does provide a ParameterNameProvider implementation following the default Bean Validation ParameterNameProvider rules as defined in 4.5.2.2. You can access it by calling getDefaultParameterNameProvider()

Via getBootstrapConfiguration(), Configuration also exposes data stored in META-INF/validation.xml

Using addMapping(), additional constraint mapping XML descriptors can be added to the configuration

Streams not supporting the mark() and reset() methods will be wrapped with an InputStream implementation supporting these methods by the Bean Validation provider in order to allow the streams to be read several times.

It is legal to invoke buildValidatorFactory() several times, e.g. in order to retrieval several ValidatorFactory instances with a slightly different configuration (see ).

A Bean Validation provider must define a sub interface of Configuration uniquely identifying the provider.

ValidationProviderResolver returns the list of Bean Validation providers available at runtime and more specifically a ValidationProvider instance for each provider available in the context.

Bean Validation providers must supply a service provider configuration file by creating a text file javax.validation.spi.ValidationProvider and placing it in the META-INF/services directory of one of its jar files.

A client can request a specific Bean Validation provider by using <T extends Configuration<T>, U extends ValidationProvider<T>> Validation.byProvider(Class<U>) or by defining the provider in the XML configuration file.

The provider discovery mechanism uses the following algorithm: Retrieve available providers using ValidationProviderResolver.getValidationProviders(). The first ValidationProvider matching the requested provider is returned. Providers are evaluated in the order they are returned by ValidationProviderResolver. A provider instance is considered matching if it is assignable to the requested provider class.

When the default Bean Validation provider is requested, the first ValidationProvider returned by the ValidationProviderResolver strategy is returned.

Every Bean Validation provider must provide a ValidationProvider implementation containing a public no-arg constructor

If a problem occurs while building the ValidatorFactory, a ValidationException is raised.

The first entry point, buildDefaultValidatorFactory(), is considered to be the default ValidatorFactory and is equivalent to the ValidatorFactory returned by Validation.byDefaultProvider().configure().buildValidatorFactory().

The second entry point lets the client provide a custom ValidationProviderResolution instance. This instance is passed to GenericBootstrap. GenericBootstrap builds a generic Configuration using the first ValidationProvider returned by ValidationProviderResolution and calling ValidationProvider.createGenericConfiguration(BootstrapState state).

The last entry point lets the client define the specific Bean Validation provider requested as well as a custom ValidationProviderResolver implementation if needed. The entry point method, Validation.byProvider(Class<U> providerType), takes the provider specific ValidationProvider implementation type and returns a ProviderSpecificBootstrap object that guarantees to return an instance of the specific Configuration sub interface.

The Validation implementation must not contain any non private attribute or method aside from the three public static bootstrap methods

The bootstrap implementation must ensure it can bootstrap third party providers.

When bootstrapping a Bean Validation provider, if the ValidationProviderResolver either fails or if the expected provider is not found, a ValidationException is raised.

Unless explicitly ignored by calling Configuration.ignoreXMLConfiguration(), a Configuration takes into account the configuration available in META-INF/validation.xml.

This configuration file is optional

Unless stated otherwise, XML based configuration settings are overridden by values explicitly set via the Configuration API.

default-provider: represents the class name of the provider specific ValidationProvider implementation class. If defined, the specific provider is used

message-interpolator: represents the fully qualified class name of the MessageInterpolator implementation. When defined in XML, the implementation must have a public no-arg constructor.

traversable-resolver: represents the fully qualified class name of the TraversableResolver implementation. When defined in XML, the implementation must have a public no-arg constructor.

constraint-validator-factory: represents the fully qualified class name of the ConstraintValidatorFactory implementation. When defined in XML, the implementation must have a public no-arg constructor.

parameter-name-provider: represents the fully qualified class name of the ParameterNameProvider implementation. When defined in XML, the implementation must have a public no-arg constructor.

message-interpolator, traversable-resolver, constraint-validator-factory, parameter-name-provider and validated-executables are optional.

constraint-mapping: represents the resource path of an XML mapping file.

More than one constraint-mapping element can be present.

Mappings provided via Configuration.addMapping(InputStream) are added to the list of mappings described via constraint-mapping.

If a public no-arg constructor is missing, a ValidationException is raised during the Configuration.buildValidatorFactory() call.

getConstraintsForClass returns a BeanDescriptor object describing the bean level constraints (see 4.1.1) and providing access to the property level constraints metadata.

An IllegalArgumentException is raised if the clazz parameter is null.

If a constraint definition or declaration hosted by the requested class (or any of it's superclasses and interfaces according to the constraint propagation rules) is invalid, a ValidationException is raised.

getElementClass returns either the object type for a class, or the returned type for a property.

getConstraintDescriptors returns all the ConstraintDescriptors (see 6.10) hosted on the given element in the class hierarchy, each ConstraintDescriptor describing one of the constraints declared on the given element.

hasConstraints returns true if the given element (class, field or property) in the class hierarchy holds at least one constraint declaration.

getKind returns the concrete type of the given element.

The method as returns the given element casted down to one of the specific descriptor types, e.g. BeanDescriptor, PropertyDescriptor etc.

unorderedAndMatchingGroups restricts to the ConstraintDescriptors (see 6.10) matching the set of groups passed as parameters and present on the element. Order is not respected but group inheritance and inheritance via sequence (including the Default group overriding at the class level) are honored.

declaredOn lets you restrict the list of element types constraints are hosted on.

lookingAt lets you restrict which constraints are considered. Either constraints belonging to the element but hosted on the class represented by BeanDescritptor (Scope.LOCAL_ELEMENT), or constraints belonging to the element but hosted anywhere in the class hierarchy (Scope.HIERARCHY).

isBeanConstrained returns true if the given class (and superclasses and interfaces) hosts at least one validation declaration (either constraint or @Valid annotation).

getConstraintsForProperty returns a PropertyDescriptor object describing the property level constraints (See 4.1.2). The property is uniquely identified by its name as per the JavaBeans convention: field level and getter level constraints of the given name are all returned.

An IllegalArgumentException is raised if the propertyName parameter is null.

getConstraintsForMethod returns a MethodDescriptor object describing the method constraints of the given method. The method is uniquely identified by its name and the types of its parameters.

getConstrainedMethods returns the MethodDescriptors of the methods having at least one constraint or cascaded parameter or return value.

getConstraintsForConstructor returns a ConstructorDescriptor ojbect describing the method constraints of the given constructor. The constructor is uniquely identified by its name and the types of its parameters.

getConstrainedConstructors returns the ConstructorDescriptors of the constructors having at least one constraint or cascaded parameter or return value.

The isCascaded method returns true if the element is marked with @Valid.

getPropertyName returns the property name as described in 5.2.

getName() returns the name of the represented method (e.g. "placeOrder") respectively the non-qualified name of the declaring class of the represented constructor (e.g. "OrderService").

getParameterDescriptors() returns a list of ParameterDescriptors representing the method's or constructor's parameters in order of their declaration, including synthetic parameters. An empty list will be returned in case the method or constructor has no parameters.

getReturnValueDescriptor() returns a descriptor for the method's or constructor's return value or null if it has no return value.

isConstrainedOnParameters() returns true if any of the parameters is constrained or cascaded or if the represented executable has at least one cross-parameter constraint. Returns false if there is no parameter.

isConstrainedOnReturnValue() returns true if the return value is constrained or cascaded. Returns false if there is no return value.

The methods hasConstraints(), getConstraintDescriptors() and findConstraints() defined on ElementDescriptor are redefined to take cross-parameter constraints into account only. Constraint descriptors for individual parameters can be obtained from the corresponding ParameterMetaData object, while constraint descriptors for the return value can be obtained from ReturnValueDescriptor.

getIndex() returns the index of the represented parameter within the parameter array of the method or constructor holding it.

getName() returns the name of the represented parameter.

If ConstraintDescriptor represents a composing annotation (see 3.3), the returned annotation must reflect parameter overriding.

getAttributes returns a map containing the annotation attribute names as a key, and the annotation attribute values as a value

If ConstraintDescriptor represents a composing annotation (see 3.3), the returned Map must reflect attribute overriding.

getGroups returns the groups the constraint is supposed to be applied upon.

If no group is set on the constraint declaration, the Default group is returned.

The groups of a composing constraint are the groups of the composed constraint.

getPayload returns the payloads associated to the constraint or an empty set if none.

The payload from the main constraint annotation is inherited by the composing annotations.

Any payload definition on a composing annotation is ignored.

isReportAsSingleViolation returns true if the constraint is annotated with @ReportAsSingleViolation.

getComposingConstraints return a set of composing ConstraintDescriptors where each descriptor describes a composing constraint.

Each Bean Validation provider must recognize built-in constraint annotations as valid constraint definitions and provide compliant constraint implementations for each.

The built-in constraint validation implementation is having a lower priority than an XML mapping definition.

@Null constraint

@NotNull constraint

@AssertTrue constraint

@AssertFalse constraint

@Min constraint

@Max constraint

@DecimalMin constraint

@DecimalMax constraint

@Size constraint

@Digits constraint

@Past constraint

@Future constraint

@Pattern constraint

If an XML descriptor does not validate against the corresponding XSD file, a ValidationException is raised.

Specifically when exploring metadata, the Bean Validation provider must ensure that an annotation instance corresponding to the XML declaration is provided via ConstraintDescriptor.getAnnnotation().

A given class must not be described more than once amongst all the XML mapping descriptors.

A given field or getter must not be described more than once on a given class description.

A given constraint definition must not be overridden more than once amongst all the XML mapping descriptors.

If any of these rule is violated in a given validation deployment, a ValidationException is raised during the creation of the ValidatorFactory.

If default-package is set, all unqualified class names (including annotations) are considered part of the package described by default-package.

A given JavaBean is described by the bean element.

The name of the class is mandatory.

By default, all constraint declarations expressed via annotation are ignored for classes described in XML.

You can force Bean Validation to consider both annotations and XML constraint declarations by using ignore-annotation="false" on bean.

If the name of the class does refer to a class not present in in the classpath, a ValidationException is raised.

If ignore-annotations is declared, Bean Validation must honor the explicit value for this element.

If not declared, the default value defined in the encapsulating bean element is considered.

When ignore-annotations is true, class-level Bean Validation annotations are ignored for this class (including the @GroupSequence).

Constraints declared in XML and constraints declared in annotations are added and form the list of class-level declared constraints.

@GroupSequence is considered unless group-sequence element is explicitly used.

If ignore-annotations is declared, Bean Validation must honor the explicit value for this element.

If not declared, the default value defined in the encapsulating bean element is considered.

When ignore-annotations is true, field-level Bean Validation annotations on the targeted field are ignored (including @Valid and @ConvertGroup).

Constraints declared in XML and constraints declared in annotations are added and form the list of field-level declared constraints.

Note that the only way to disable cascading on a field marked as @Valid is to use ignore-annotations=true.

If the name of the field does not correspond to a field in the given bean a ValidationException is raised.

The name attribute corresponds to the name of the property considered as defined in 4.1.2 (for example a getter String getAge() would have <getter name="age"/> as a corresponding descriptor). If ignore-annotations is declared, Bean Validation must honor the explicit value for this element.

If not declared, the default value defined in the encapsulating bean element is considered.

When ignore-annotations is true, property-level Bean Validation annotations on the targeted property are ignored (including @Valid and @ConvertGroup).

Constraints declared in XML and constraints declared in annotations are added and form the list of property-level declared constraints.

Note that the only way to disable cascading on a property marked as @Valid is to use ignore-annotations=true.

If the name of the property does not correspond to a property in the given bean a ValidationException is raised.

The name attribute is mandatory and represents the name of the element in the constraint declaration.

Message, groups and payload are not permitted names, use the message, groups or payload elements instead. Otherwise a ValidationException is raised.

If the element represents a primitive type, a class or an enum, the string representation of its value is placed in the element itself.

If the element represents a primitive type array, a class array or an enum array, the string representation of each value is placed in a value element placed under the element itself.

If the element represents an annotation, the annotation element is used to represent the annotation and placed under element.

If the element represents an array of annotations, one or more annotation elements are placed under element.

Elements with default values in the annotation definition do not have to be represented in XML: the default value will be used in this case.

If an XML constraint declaration is missing mandatory elements, or if it contains elements not part of the constraint definition, a ValidationException is raised.

A constraint definition is represented by a constraint-definition element.

If include-existing-validator is set to false, ConstraintValidator defined on the constraint annotation are ignored.

If set to true, the list of ConstraintValidators described in XML are concatenated to the list of ConstraintValidator described on the annotation to form a new array of ConstraintValidator evaluated.

Annotation based ConstraintValidator come before XML based ConstraintValidators in the array.

The new validator list is returned by ConstraintDescriptor.getConstraintValidatorClasses().

If the version attribute attribute is not given, schema version 1.0 is to be assumed by the Bean Validation Provider.

In case an unknown version is given (e.g. if a mapping descriptor adhering to a future schema version is parsed by a Bean Validation 1.1 provider) a ValidationException is raised.

In case an unknown version is given a ValidationException is raised.

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 does not respect the Bean Validation rules or is inconsistent, a ConstraintDefinitionException is raised.

When the return type of a property cannot be processed for a given constraint, an UnexpectedTypeException is raised.

When a group definition is illegal, GroupDefinitionException is raised.