# Metadata API

The Bean Validation specification provides not only a validation engine, but also a metadata repository for all defined constraints. The following paragraphs are discussing this API. All the introduced classes can be found in the javax.validation.metadata package.

## BeanDescriptor

The entry into the metadata API is via `Validator.getConstraintsForClass` which returns an instance of the BeanDescriptor interface. Using this bean descriptor you can determine whether the specified class hosts any constraints at all via `beanDescriptor.isBeanConstrained`.

If a constraint declaration hosted by the requested class is invalid, a ValidationException is thrown.

You can then call `beanDescriptor.getConstraintDescriptors` to get a set of ConstraintDescriptors representing all class level constraints.

If you are interested in property level constraints, you can call `beanDescriptor.getConstraintsForProperty` or `beanDescriptor.getConstrainedProperties` to get a single resp. set of PropertyDescriptors (see ).

## PropertyDescriptor

The PropertyDescriptor interface extends the ElementDescriptor interface and represents constraints on properties of a class. The constraint can be declared on the attribute itself or on the getter of the attribute - provided Java Bean naming conventions are respected. A PropertyDescriptor adds `isCascaded` (returning `true` if the property is marked with @Valid) and `getPropertyName` to the ElementDescriptor functionality.

## ElementDescriptor

The ElementDiscriptor interface is the common base class for BeanDescriptor and PropertyDescriptor. Next to the `hasConstraints` and `getConstraintDescriptors` methods it also offers access to the ConstraintFinder API which allows you to query the metadata API in a more fine grained way. For example you can restrict your search to constraints described on fields or on getters or a given set of groups. Given an ElementDescriptor instance you just call `findConstraints` to retrieve a ConstraintFinder instance.

Usage of ConstraintFinder

    Validator validator = Validation.buildDefaultValidatorFactory().getValidator();
    BeanDescriptor beanDescriptor = validator.getConstraintsForClass(Person.class);
    PropertyDescriptor propertyDescriptor = beanDescriptor.getConstraintsForProperty("name");
    Set<ConstraintDescriptor<?>> constraints = propertyDescriptor.findConstraints()
                                               .declaredOn(ElementType.METHOD)
                                               .unorderedAndMatchingGroups(Default.class)
                                               .lookingAt(Scope.LOCAL_ELEMENT)
                                               .getConstraintDescriptors();

shows an example on how to use the ConstraintFinder API. Interesting are especially the restrictions `unorderedAndMatchingGroups` and `lookingAt(Scope.LOCAL_ELEMENT)`. The former allows to only return ConstraintDescriptors matching a specified set of groups wheras the latter allows to distinguish between constraint directly specified on the element (`Scope.LOCAL_ELEMENT`) or constraints belonging to the element but hosted anywhere in the class hierarchy (`Scope.HIERARCHY`).

Order is not respected by unorderedAndMatchingGroups, but group inheritance and inheritance via sequence are.

## ConstraintDescriptor

Last but not least, the ConstraintDescriptor interface describes a single constraint together with its composing constraints. Via an instance of this interface you get access to the constraint annotation and its parameters, as well as the groups the constraint is supposed to be applied on. It also also you to access the pass-through constraint payload (see ).