Bean Validation specification

/**
 * Marks an annotation as being a Bean Validation constraint.
 * <p>
 * A given constraint annotation must be annotated by a {@code @Constraint}
 * annotation which refers to its list of constraint validation implementations.
 * <p>
 * Each constraint annotation must host the following attributes:
 * <ul>
 *     <li>{@code String message() default [...];} which should default to an error
 *     message key made of the fully-qualified class name of the constraint followed by
 *     {@code .message}. For example {@code "{com.acme.constraints.NotSafe.message}"}</li>
 *     <li>{@code Class<?>[] groups() default {};} for user to customize the targeted
 *     groups</li>
 *     <li>{@code Class<? extends Payload>[] payload() default {};} for
 *     extensibility purposes</li>
 * </ul>
 * <p>
 * When building a constraint that is both generic and cross-parameter, the constraint
 * annotation must host the {@code validationAppliesTo()} property.
 * A constraint is generic if it targets the annotated element and is cross-parameter if
 * it targets the array of parameters of a method or constructor.
 * <pre>
 *     ConstraintTarget validationAppliesTo() default ConstraintTarget.IMPLICIT;
 * </pre>
 * This property allows the constraint user to choose whether the constraint
 * targets the return type of the executable or its array of parameters.
 *
 * A constraint is both generic and cross-parameter if
 * <ul>
 *     <li>two kinds of {@code ConstraintValidator}s are attached to the
 *     constraint, one targeting {@link ValidationTarget#ANNOTATED_ELEMENT}
 *     and one targeting {@link ValidationTarget#PARAMETERS},</li>
 *     <li>or if a {@code ConstraintValidator} targets both
 *     {@code ANNOTATED_ELEMENT} and {@code PARAMETERS}.</li>
 * </ul>
 *
 * Such dual constraints are rare. See {@link SupportedValidationTarget} for more info.
 * <p>
 * Here is an example of constraint definition:
 * <pre>
 * &#64;Documented
 * &#64;Constraint(validatedBy = OrderNumberValidator.class)
 * &#64;Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
 * &#64;Retention(RUNTIME)
 * public &#64;interface OrderNumber {
 *     String message() default "{com.acme.constraint.OrderNumber.message}";
 *     Class&lt;?&gt;[] groups() default {};
 *     Class&lt;? extends Payload&gt;[] payload() default {};
 * }
 * </pre>
 *
 * @author Emmanuel Bernard
 * @author Gavin King
 * @author Hardy Ferentschik
 */
@Documented
@Target({ ANNOTATION_TYPE })
@Retention(RUNTIME)
public @interface Constraint {

    /**
     * {@link ConstraintValidator} classes implementing the constraint. The given classes
     * must reference distinct target types for a given {@link ValidationTarget}. If two
     * {@code ConstraintValidator}s refer to the same type, an exception will occur.
     * <p>
     * At most one {@code ConstraintValidator} targeting the array of parameters of
     * methods or constructors (aka cross-parameter) is accepted. If two or more
     * are present, an exception will occur.
     *
     * @return array of {@code ConstraintValidator} classes implementing the constraint
     */
    Class<? extends ConstraintValidator<?, ?>>[] validatedBy();
}

/**
 * A constraint annotation hosting this annotation will return the
 * composed annotation error report if any of the composing annotations fail.
 * The error reports of each individual composing constraint are ignored.
 * <p>
 * Note: Evaluation of composed constraints stops on the first validation
 * error in case the composing constraint is annotated with
 * {@code @ReportAsSingleViolation}.
 *
 * @author Emmanuel Bernard
 */
@Target({ ANNOTATION_TYPE })
@Retention(RUNTIME)
@Documented
public @interface ReportAsSingleViolation {
}

/**
 * Marks an attribute as overriding the attribute of a composing constraint.
 * Both attributes must share the same type.
 *
 * @author Emmanuel Bernard
 */
@Documented
@Retention(RUNTIME)
@Target({ METHOD })
@Repeatable(List.class)
public @interface OverridesAttribute {

    /**
     * @return constraint type the attribute is overriding
     */
    Class<? extends Annotation> constraint();

    /**
     * Name of the Constraint attribute overridden.
     * Defaults to the name of the attribute hosting {@code @OverridesAttribute}.
     *
     * @return name of constraint attribute overridden
     */
    String name() default "";

    /**
     * The index of the targeted constraint declaration when using
     * multiple constraints of the same type.
     * <p>
     * The index represents the index of the constraint in the
     * {@code value()} array.
     * <p>
     * By default, no index is defined and the single constraint declaration
     * is targeted.
     *
     * @return constraint declaration index if multivalued annotation is used
     */
    int constraintIndex() default -1;

    /**
     * Defines several {@link OverridesAttribute} annotations on the same element
     *
     * @see javax.validation.OverridesAttribute
     */
    @Documented
    @Target({ METHOD })
    @Retention(RUNTIME)
    public @interface List {

        OverridesAttribute[] value();
    }
}

/**
 * Defines the logic to validate a given constraint {@code A}
 * for a given object type {@code T}.
 * <p>
 * Implementations must comply to the following restriction:
 * <ul>
 *     <li>{@code T} must resolve to a non parameterized type</li>
 *     <li>or generic parameters of {@code T} must be unbounded
 *     wildcard types</li>
 * </ul>
 * <p>
 * The annotation {@link SupportedValidationTarget} can be put on a
 * {@code ConstraintValidator} implementation to mark it as supporting
 * cross-parameter constraints. Check out {@link SupportedValidationTarget}
 * and {@link Constraint} for more information.
 *
 * @param <A> the annotation type handled by an implementation
 * @param <T> the target type supported by an implementation
 *
 * @author Emmanuel Bernard
 * @author Hardy Ferentschik
 */
public interface ConstraintValidator<A extends Annotation, T> {

    /**
     * Initializes the validator in preparation for
     * {@link #isValid(Object, ConstraintValidatorContext)} calls.
     * The constraint annotation for a given constraint declaration
     * is passed.
     * <p>
     * This method is guaranteed to be called before any use of this instance for
     * validation.
     * <p>
     * The default implementation is a no-op.
     *
     * @param constraintAnnotation annotation instance for a given constraint declaration
     */
    default void initialize(A constraintAnnotation) {
    }

    /**
     * Implements the validation logic.
     * The state of {@code value} must not be altered.
     * <p>
     * This method can be accessed concurrently, thread-safety must be ensured
     * by the implementation.
     *
     * @param value object to validate
     * @param context context in which the constraint is evaluated
     *
     * @return {@code false} if {@code value} does not pass the constraint
     */
    boolean isValid(T value, ConstraintValidatorContext context);
}

package javax.validation.constraintvalidation;

/**
 * Defines the target(s) a {@link ConstraintValidator} can validate.
 * <p>
 * A {@code ConstraintValidator} can target the (returned) element
 * annotated by the constraint, the array of parameters of a method
 * or constructor (aka cross-parameter) or both.
 * <p>
 * If {@code @SupportedValidationTarget} is not present, the
 * {@code ConstraintValidator} targets the (returned) element annotated
 * by the constraint.
 * <p>
 * A {@code ConstraintValidator} targeting cross-parameter must accept
 * {@code Object[]} (or {@code Object}) as the type of object it validates.
 *
 * @author Emmanuel Bernard
 * @since 1.1
 */
@Documented
@Target({ TYPE })
@Retention(RUNTIME)
public @interface SupportedValidationTarget {

    ValidationTarget[] value();
}

package javax.validation.constraintvalidation;

/**
 * List of possible targets for a {@link ConstraintValidator}.
 *
 * @author Emmanuel Bernard
 * @since 1.1
 */
public enum ValidationTarget {

    /**
     * (Returned) element annotated by the constraint.
     */
    ANNOTATED_ELEMENT,

    /**
     * Array of parameters of the annotated method or constructor (aka cross-parameter).
     */
    PARAMETERS
}

/**
 * Provides contextual data and operation when applying a given constraint validator.
 *
 * At least one {@link ConstraintViolation} must be defined (either the default one,
 * of if the default {@code ConstraintViolation} is disabled, a custom one).
 *
 * @author Emmanuel Bernard
 * @author Guillaume Smet
 */
public interface ConstraintValidatorContext {

    /**
     * Disables the default {@link ConstraintViolation} object generation (which
     * is using the message template declared on the constraint).
     * <p>
     * Useful to set a different violation message or generate a {@code ConstraintViolation}
     * based on a different property.
     */
    void disableDefaultConstraintViolation();

    /**
     * @return the current un-interpolated default message
     */
    String getDefaultConstraintMessageTemplate();

    /**
     * Returns the provider for obtaining the current time in the form of a {@link Clock},
     * e.g. when validating the {@code Future} and {@code Past} constraints.
     *
     * @return the provider for obtaining the current time, never {@code null}. If no
     * specific provider has been configured during bootstrap, a default implementation using
     * the current system time and the current default time zone as returned by
     * {@link Clock#systemDefaultZone()} will be returned.
     *
     * @since 2.0
     */
    ClockProvider getClockProvider();

    /**
     * Returns a constraint violation builder building a violation report
     * allowing to optionally associate it to a sub path.
     * The violation message will be interpolated.
     * <p>
     * To create the {@link ConstraintViolation}, one must call either one of
     * the {@code addConstraintViolation()} methods available in one of the
     * interfaces of the fluent API.
     * If another method is called after {@code addConstraintViolation()} on
     * {@code ConstraintViolationBuilder} or any of its associated nested interfaces
     * an {@code IllegalStateException} is raised.
     * <p>
     * If {@link ConstraintValidator#isValid(Object, ConstraintValidatorContext)} returns
     * {@code false}, a {@code ConstraintViolation} object will be built per constraint
     * violation report including the default one (unless
     * {@link #disableDefaultConstraintViolation()} has been called).
     * <p>
     * {@code ConstraintViolation} objects generated from such a call
     * contain the same contextual information (root bean, path and so on) unless
     * the path has been overridden.
     * <p>
     * To create a different {@code ConstraintViolation}, a new constraint violation builder
     * has to be retrieved from {@code ConstraintValidatorContext}
     *
     * Here are a few usage examples:
     * <pre>
     * //assuming the following domain model
     * public class User {
     *     public Map&lt;String,Address&gt; getAddresses() { ... }
     * }
     *
     * public class Address {
     *     public String getStreet() { ... }
     *     public Country getCountry() { ... }
     * }
     *
     * public class Country {
     *     public String getName() { ... }
     * }
     *
     * //From a property-level constraint on User.addresses
     * //Build a constraint violation on the default path - i.e. the "addresses" property
     * context.buildConstraintViolationWithTemplate( "this detail is wrong" )
     *             .addConstraintViolation();
     *
     * //From a class level constraint on Address
     * //Build a constraint violation on the default path + "street"
     * //i.e. the street property of Address
     * context.buildConstraintViolationWithTemplate( "this detail is wrong" )
     *             .addPropertyNode( "street" )
     *             .addConstraintViolation();
     *
     * //From a property-level constraint on  User.addresses
     * //Build a constraint violation on the default path + the bean stored
     * //under the "home" key in the map
     * context.buildConstraintViolationWithTemplate( "Incorrect home address" )
     *             .addBeanNode()
     *                 .inContainer( Map.class, 1 )
     *                 .inIterable().atKey( "home" )
     *             .addConstraintViolation();
     *
     * //From a class level constraint on User
     * //Build a constraint violation on the default path + addresses["home"].country.name
     * //i.e. property "country.name" on the object stored under "home" in the map
     * context.buildConstraintViolationWithTemplate( "this detail is wrong" )
     *             .addPropertyNode( "addresses" )
     *             .addPropertyNode( "country" )
     *                 .inContainer( Map.class, 1 )
     *                 .inIterable().atKey( "home" )
     *             .addPropertyNode( "name" )
     *             .addConstraintViolation();
     *
     * //From a class level constraint on User
     * //Build a constraint violation on the default path + addresses["home"].&lt;map key&gt;
     * //i.e. a container element constraint violation for the map key
     * context.buildConstraintViolationWithTemplate( "the map key is invalid" )
     *             .addPropertyNode( "addresses" )
     *             .addContainerElementNode( "&lt;map key&gt;", Map.class, 0 )
     *                 .inIterable().atKey( "invalid" )
     *             .addConstraintViolation();
     * </pre>
     * <p>
     * Cross-parameter constraints on a method can create a node specific
     * to a particular parameter if required. Let's explore a few examples:
     * <pre>
     * //Cross-parameter constraint on method
     * //createUser(String password, String passwordRepeat)
     * //Build a constraint violation on the default path + "passwordRepeat"
     * context.buildConstraintViolationWithTemplate("Passwords do not match")
     *             .addParameterNode(1)
     *             .addConstraintViolation();
     *
     * //Cross-parameter constraint on a method
     * //mergeAddresses(Map&lt;String,Address&gt; addresses,
     * //        Map&lt;String,Address&gt; otherAddresses)
     * //Build a constraint violation on the default path + "otherAddresses["home"]
     * //i.e. the Address bean hosted in the "home" key of the "otherAddresses" map parameter
     * context.buildConstraintViolationWithTemplate(
     *         "Map entry home present in both and does not match")
     *             .addParameterNode(1)
     *             .addBeanNode()
     *                 .inContainer( Map.class, 1 )
     *                 .inIterable().atKey("home")
     *             .addConstraintViolation();
     *
     * //Cross-parameter constraint on a method
     * //mergeAddresses(Map&lt;String,Address&gt; addresses,
     * //        Map&lt;String,Address&gt; otherAddresses)
     * //Build a constraint violation on the default path + "otherAddresses["home"].city
     * //i.e. on the "city" property of the Address bean hosted in
     * //the "home" key of the "otherAddresses" map
     * context.buildConstraintViolationWithTemplate(
     *         "Map entry home present in both but city does not match")
     *             .addParameterNode(1)
     *             .addPropertyNode("city")
     *                 .inContainer( Map.class, 1 )
     *                 .inIterable().atKey("home")
     *             .addConstraintViolation();
     * </pre>
     *
     * @param messageTemplate new un-interpolated constraint message
     * @return returns a constraint violation builder
     */
    ConstraintViolationBuilder buildConstraintViolationWithTemplate(String messageTemplate);

    /**
     * Returns an instance of the specified type allowing access to
     * provider-specific APIs. If the Bean Validation provider
     * implementation does not support the specified class,
     * {@link ValidationException} is thrown.
     *
     * @param type the class of the object to be returned
     * @param <T> the type of the object to be returned
     * @return an instance of the specified class
     * @throws ValidationException if the provider does not support the call
     *
     * @since 1.1
     */
    <T> T unwrap(Class<T> type);

    /**
     * {@link ConstraintViolation} builder allowing to optionally associate
     * the violation report to a sub path.
     * <p>
     * To create the {@code ConstraintViolation}, one must call either one of
     * the {@code addConstraintViolation()} methods available in one of the
     * interfaces of the fluent API.
     * <p>
     * If another method is called after {@code addConstraintViolation()} on
     * {@code ConstraintViolationBuilder} or any of its associated objects
     * an {@code IllegalStateException} is raised.
     */
    interface ConstraintViolationBuilder {

        /**
         * Adds a node to the path the {@link ConstraintViolation} will be associated to.
         * <p>
         * {@code name} describes a single property. In particular,
         * dot (.) is not allowed.
         *
         * @param name property name
         * @return a builder representing node {@code name}
         * @deprecated since 1.1 - replaced by {@link #addPropertyNode(String)},
         *             {@link #addBeanNode()} and {@link #addParameterNode(int)}
         */
        NodeBuilderDefinedContext addNode(String name);

        /**
         * Adds a property node to the path the {@link ConstraintViolation}
         * will be associated to.
         * <p>
         * {@code name} describes a single property. In particular,
         * dot (.) is not allowed.
         *
         * @param name property name
         * @return a builder representing node {@code name}
         * @throws IllegalArgumentException if the name is null
         *
         * @since 1.1
         */
        NodeBuilderCustomizableContext addPropertyNode(String name);

        /**
         * Adds a bean node (class-level) to the path the {@link ConstraintViolation}
         * will be associated to.
         * Note that bean nodes are always leaf nodes.
         *
         * @return a builder representing the bean node
         *
         * @since 1.1
         */
        LeafNodeBuilderCustomizableContext addBeanNode();

        /**
         * Adds a container element node to the path the {@link ConstraintViolation}
         * will be associated to.
         *
         * @param name the node name
         * @param containerType the type of the container
         * @param typeArgumentIndex the index of the type argument
         * @return a builder representing the container element node
         * @throws IllegalArgumentException if the index is not valid
         *
         * @since 2.0
         */
        ContainerElementNodeBuilderCustomizableContext addContainerElementNode(String name,
                Class<?> containerType, Integer typeArgumentIndex);

        /**
         * Adds a method parameter node to the path the {@link ConstraintViolation}
         * will be associated to.
         * The parameter index must be valid (i.e. within the boundaries of the method
         * parameter indexes). May only be called from within cross-parameter validators.
         *
         * @param index the parameter index
         * @return a builder representing the index-th parameter node
         * @throws IllegalArgumentException if the index is not valid
         *
         * @since 1.1
         */
        NodeBuilderDefinedContext addParameterNode(int index);

        /**
         * Adds the new {@link ConstraintViolation} to be generated if the
         * constraint validator marks the value as invalid.
         * <p>
         * Methods of this {@code ConstraintViolationBuilder} instance and its nested
         * objects throw {@code IllegalStateException} from now on.
         *
         * @return the {@code ConstraintValidatorContext} instance the
         *         {@code ConstraintViolationBuilder} comes from
         */
        ConstraintValidatorContext addConstraintViolation();

        /**
         * Represents a node whose context is known
         * (i.e. index, key and isInIterable)
         * and that is a leaf node (i.e. no subnode can be added).
         *
         * @since 1.1
         */
        interface LeafNodeBuilderDefinedContext {

            /**
             * Adds the new {@link ConstraintViolation} to be generated if the
             * constraint validator marks the value as invalid.
             * <p>
             * Methods of the {@code ConstraintViolationBuilder} instance this object
             * comes from and the constraint violation builder nested
             * objects throw {@code IllegalStateException} after this call.
             *
             * @return {@code ConstraintValidatorContext} instance the
             *         {@code ConstraintViolationBuilder} comes from
             */
            ConstraintValidatorContext addConstraintViolation();
        }

        /**
         * Represents a node whose context is
         * configurable (i.e. index, key and isInIterable)
         * and that is a leaf node (i.e. no subnode can be added).
         *
         * @since 1.1
         */
        interface LeafNodeBuilderCustomizableContext {

            /**
             * Marks the node as being in an iterable, e.g. array, {@code Iterable} or a
             * {@code Map}.
             *
             * @return a builder representing iterable details
             */
            LeafNodeContextBuilder inIterable();

            /**
             * Marks the node as being in a container such as a {@code List}, {@code Map} or
             * {@code Optional}.
             *
             * @param containerClass the type of the container
             * @param typeArgumentIndex type index of the concerned type argument
             * @return a builder representing the current node
             * @throws IllegalArgumentException if the index is not valid
             *
             * @since 2.0
             */
            LeafNodeBuilderCustomizableContext inContainer(Class<?> containerClass,
                                                           Integer typeArgumentIndex);

            /**
             * Adds the new {@link ConstraintViolation} to be generated if the
             * constraint validator mark the value as invalid.
             * <p>
             * Methods of the {@code ConstraintViolationBuilder} instance this object
             * comes from and the constraint violation builder nested
             * objects throw {@code IllegalStateException} after this call.
             *
             * @return {@code ConstraintValidatorContext} instance the
             *         {@code ConstraintViolationBuilder} comes from
             */
            ConstraintValidatorContext addConstraintViolation();
        }

        /**
         * Represents refinement choices for a node which is
         * in an iterable, e.g. array, {@code Iterable} or {@code Map}.
         * <p>
         * If the iterable is an indexed collection or a map,
         * the index or the key should be set.
         * <p>
         * The node is a leaf node (i.e. no subnode can be added).
         *
         * @since 1.1
         */
        interface LeafNodeContextBuilder {

            /**
             * Defines the key the object is into the {@code Map}.
             *
             * @param key map key
             * @return a builder representing the current node
             */
            LeafNodeBuilderDefinedContext atKey(Object key);

            /**
             * Defines the index the object is into the {@code List} or array
             *
             * @param index index
             * @return a builder representing the current node
             */
            LeafNodeBuilderDefinedContext atIndex(Integer index);

            /**
             * Adds the new {@link ConstraintViolation} to be generated if the
             * constraint validator mark the value as invalid.
             * <p>
             * Methods of the {@code ConstraintViolationBuilder} instance this object
             * comes from and the constraint violation builder nested
             * objects throw {@code IllegalStateException} after this call.
             *
             * @return {@code ConstraintValidatorContext} instance the
             *           {@code ConstraintViolationBuilder} comes from
             */
            ConstraintValidatorContext addConstraintViolation();
        }

        /**
         * Represents a node whose context is known
         * (i.e. index, key and isInIterable)
         * and that is not necessarily a leaf node (i.e. subnodes can
         * be added).
         */
        interface NodeBuilderDefinedContext {

            /**
             * Adds a node to the path the {@link ConstraintViolation} will be associated to.
             * <p>
             * {@code name} describes a single property. In particular,
             * dot (.) is not allowed.
             *
             * @param name property name
             * @return a builder representing node {@code name}
             * @deprecated since 1.1 - replaced by {@link #addPropertyNode(String)}
             *             and {@link #addBeanNode()}
             */
            NodeBuilderCustomizableContext addNode(String name);

            /**
             * Adds a property node to the path the {@link ConstraintViolation}
             * will be associated to.
             * <p>
             * {@code name} describes a single property. In particular,
             * dot (.) is not allowed.
             *
             * @param name property name
             * @return a builder representing node {@code name}
             * @throws IllegalArgumentException if the name is null
             *
             * @since 1.1
             */
            NodeBuilderCustomizableContext addPropertyNode(String name);

            /**
             * Adds a bean node (class-level) to the path the {@link ConstraintViolation}
             * will be associated to.
             * Note that bean nodes are always leaf nodes.
             *
             * @return a builder representing the bean node
             *
             * @since 1.1
             */
            LeafNodeBuilderCustomizableContext addBeanNode();

            /**
             * Adds a container element node to the path the {@link ConstraintViolation}
             * will be associated to.
             *
             * @param name the node name
             * @param containerType the type of the container
             * @param typeArgumentIndex the index of the type argument
             * @return a builder representing the container element node
             * @throws IllegalArgumentException if the index is not valid
             *
             * @since 2.0
             */
            ContainerElementNodeBuilderCustomizableContext addContainerElementNode(
                    String name, Class<?> containerType, Integer typeArgumentIndex);

            /**
             * Adds the new {@link ConstraintViolation} to be generated if the
             * constraint validator marks the value as invalid.
             * <p>
             * Methods of the {@code ConstraintViolationBuilder} instance this object
             * comes from and the constraint violation builder nested
             * objects throw {@code IllegalStateException} after this call.
             *
             * @return {@code ConstraintValidatorContext} instance the
             *           {@code ConstraintViolationBuilder} comes from
             */
            ConstraintValidatorContext addConstraintViolation();
        }

        /**
         * Represents a node whose context is
         * configurable (i.e. index, key and isInIterable)
         * and that is not necessarily a leaf node (i.e. subnodes can
         * be added).
         */
        interface NodeBuilderCustomizableContext {

            /**
             * Marks the node as being in an iterable, e.g. array, {@code Iterable} or a
             * {@code Map}.
             *
             * @return a builder representing iterable details
             */
            NodeContextBuilder inIterable();

            /**
             * Marks the node as being in a container such as a {@code List}, {@code Map} or
             * {@code Optional}.
             *
             * @param containerClass the type of the container
             * @param typeArgumentIndex type index of the concerned type argument
             * @return a builder representing the current node
             * @throws IllegalArgumentException if the index is not valid
             *
             * @since 2.0
             */
            NodeBuilderCustomizableContext inContainer(Class<?> containerClass,
                                                       Integer typeArgumentIndex);

            /**
             * Adds a node to the path the {@link ConstraintViolation} will be associated to.
             *
             * {@code name} describes a single property. In particular,
             * dot (.) is not allowed.
             *
             * @param name property name
             * @return a builder representing node {@code name}
             * @deprecated since 1.1 - replaced by {@link #addPropertyNode(String)}
             *             and {@link #addBeanNode()}
             */
            NodeBuilderCustomizableContext addNode(String name);

            /**
             * Adds a property node to the path the {@link ConstraintViolation}
             * will be associated to.
             *
             * {@code name} describes a single property. In particular,
             * dot (.) is not allowed.
             *
             * @param name property name
             * @return a builder representing node {@code name}
             * @throws IllegalArgumentException if the name is null
             *
             * @since 1.1
             */
            NodeBuilderCustomizableContext addPropertyNode(String name);

            /**
             * Adds a bean node (class-level) to the path the {@link ConstraintViolation}
             * will be associated to.
             * Note that bean nodes are always leaf nodes.
             *
             * @return a builder representing the bean node
             *
             * @since 1.1
             */
            LeafNodeBuilderCustomizableContext addBeanNode();

            /**
             * Adds a container element node to the path the {@link ConstraintViolation}
             * will be associated to.
             *
             * @param name the node name
             * @param containerType the type of the container
             * @param typeArgumentIndex the index of the type argument
             * @return a builder representing the container element node
             * @throws IllegalArgumentException if the index is not valid
             *
             * @since 2.0
             */
            ContainerElementNodeBuilderCustomizableContext addContainerElementNode(
                    String name, Class<?> containerType, Integer typeArgumentIndex);

            /**
             * Adds the new {@link ConstraintViolation} to be generated if the
             * constraint validator mark the value as invalid.
             * <p>
             * Methods of the {@code ConstraintViolationBuilder} instance this object
             * comes from and the constraint violation builder nested
             * objects throw {@code IllegalStateException} after this call.
             *
             * @return {@code ConstraintValidatorContext} instance the
             *           {@code ConstraintViolationBuilder} comes from
             */
            ConstraintValidatorContext addConstraintViolation();
        }

        /**
         * Represents refinement choices for a node which is
         * in an iterable, e.g. array, {@code Iterable} or {@code Map}.
         * <p>
         * If the iterable is an indexed collection or a map,
         * the index or the key should be set.
         * <p>
         * The node is not necessarily a leaf node (i.e. subnodes can
         * be added).
         */
        interface NodeContextBuilder {

            /**
             * Defines the key the object is into the {@code Map}.
             *
             * @param key map key
             * @return a builder representing the current node
             */
            NodeBuilderDefinedContext atKey(Object key);

            /**
             * Defines the index the object is into the {@code List} or array.
             *
             * @param index index
             * @return a builder representing the current node
             */
            NodeBuilderDefinedContext atIndex(Integer index);

            /**
             * Adds a node to the path the {@code ConstraintViolation} will be associated to.
             *
             * {@code name} describes a single property. In particular,
             * dot (.) is not allowed.
             *
             * @param name property name
             * @return a builder representing node {@code name}
             * @deprecated since 1.1 - replaced by {@link #addPropertyNode(String)}
             *             and {@link #addBeanNode()}
             */
            NodeBuilderCustomizableContext addNode(String name);

            /**
             * Adds a property node to the path the {@link ConstraintViolation}
             * will be associated to.
             *
             * {@code name} describes a single property. In particular,
             * dot (.) is not allowed.
             *
             * @param name property name
             * @return a builder representing node {@code name}
             * @throws IllegalArgumentException if the name is null
             *
             * @since 1.1
             */
            NodeBuilderCustomizableContext addPropertyNode(String name);

            /**
             * Adds a bean node (class-level) to the path the {@link ConstraintViolation}
             * will be associated to.
             * <p>
             * Note that bean nodes are always leaf nodes.
             *
             * @return a builder representing the bean node
             *
             * @since 1.1
             */
            LeafNodeBuilderCustomizableContext addBeanNode();

            /**
             * Adds a container element node to the path the {@link ConstraintViolation}
             * will be associated to.
             *
             * @param name the node name
             * @param containerType the type of the container
             * @param typeArgumentIndex the index of the type argument
             * @return a builder representing the container element node
             * @throws IllegalArgumentException if the index is not valid
             *
             * @since 2.0
             */
            ContainerElementNodeBuilderCustomizableContext addContainerElementNode(
                    String name, Class<?> containerType, Integer typeArgumentIndex);

            /**
             * Adds the new {@link ConstraintViolation} to be generated if the
             * constraint validator mark the value as invalid.
             * <p>
             * Methods of the {@code ConstraintViolationBuilder} instance this object
             * comes from and the constraint violation builder nested
             * objects throw {@code IllegalStateException} after this call.
             *
             * @return {@code ConstraintValidatorContext} instance the
             *         {@code ConstraintViolationBuilder} comes from
             */
            ConstraintValidatorContext addConstraintViolation();
        }

        /**
         * Represents a container element node whose context is known
         * (i.e. index, key and isInIterable)
         * and that is not necessarily a leaf node (i.e. subnodes can
         * be added).
         *
         * @since 2.0
         */
        interface ContainerElementNodeBuilderDefinedContext {

            /**
             * Adds a property node to the path the {@link ConstraintViolation}
             * will be associated to.
             * <p>
             * {@code name} describes a single property. In particular,
             * dot (.) is not allowed.
             *
             * @param name property name
             * @return a builder representing node {@code name}
             * @throws IllegalArgumentException if the name is null
             */
            NodeBuilderCustomizableContext addPropertyNode(String name);

            /**
             * Adds a bean node (class-level) to the path the {@link ConstraintViolation}
             * will be associated to.
             * Note that bean nodes are always leaf nodes.
             *
             * @return a builder representing the bean node
             */
            LeafNodeBuilderCustomizableContext addBeanNode();

            /**
             * Adds a container element node to the path the {@link ConstraintViolation}
             * will be associated to.
             *
             * @param name the node name
             * @param containerType the type of the container
             * @param typeArgumentIndex the index of the type argument
             * @return a builder representing the container element node
             * @throws IllegalArgumentException if the index is not valid
             */
            ContainerElementNodeBuilderCustomizableContext addContainerElementNode(
                    String name, Class<?> containerType, Integer typeArgumentIndex);

            /**
             * Adds the new {@link ConstraintViolation} to be generated if the
             * constraint validator marks the value as invalid.
             * <p>
             * Methods of the {@code ConstraintViolationBuilder} instance this object
             * comes from and the constraint violation builder nested
             * objects throw {@code IllegalStateException} after this call.
             *
             * @return {@code ConstraintValidatorContext} instance the
             *           {@code ConstraintViolationBuilder} comes from
             */
            ConstraintValidatorContext addConstraintViolation();
        }

        /**
         * Represents a container element node whose context is
         * configurable (i.e. index, key and isInIterable)
         * and that is not necessarily a leaf node (i.e. subnodes can
         * be added).
         *
         * @since 2.0
         */
        interface ContainerElementNodeBuilderCustomizableContext {

            /**
             * Marks the node as being in an iterable, e.g. array, {@code Iterable} or a
             * {@code Map}.
             *
             * @return a builder representing iterable details
             */
            ContainerElementNodeContextBuilder inIterable();

            /**
             * Adds a property node to the path the {@link ConstraintViolation}
             * will be associated to.
             *
             * {@code name} describes a single property. In particular,
             * dot (.) is not allowed.
             *
             * @param name property name
             * @return a builder representing node {@code name}
             * @throws IllegalArgumentException if the name is null
             */
            NodeBuilderCustomizableContext addPropertyNode(String name);

            /**
             * Adds a bean node (class-level) to the path the {@link ConstraintViolation}
             * will be associated to.
             * <p>
             * Note that bean nodes are always leaf nodes.
             *
             * @return a builder representing the bean node
             */
            LeafNodeBuilderCustomizableContext addBeanNode();

            /**
             * Adds a container element node to the path the {@link ConstraintViolation}
             * will be associated to.
             *
             * @param name the node name
             * @param containerType the type of the container
             * @param typeArgumentIndex the index of the type argument
             * @return a builder representing the container element node
             * @throws IllegalArgumentException if the index is not valid
             */
            ContainerElementNodeBuilderCustomizableContext addContainerElementNode(
                    String name, Class<?> containerType, Integer typeArgumentIndex);

            /**
             * Adds the new {@link ConstraintViolation} to be generated if the
             * constraint validator mark the value as invalid.
             * <p>
             * Methods of the {@code ConstraintViolationBuilder} instance this object
             * comes from and the constraint violation builder nested
             * objects throw {@code IllegalStateException} after this call.
             *
             * @return {@code ConstraintValidatorContext} instance the
             *         {@code ConstraintViolationBuilder} comes from
             */
            ConstraintValidatorContext addConstraintViolation();
        }

        /**
         * Represents refinement choices for a container element node.
         * <p>
         * If the container is an indexed collection or a map,
         * the index or the key should be set.
         * <p>
         * The node is not necessarily a leaf node (i.e. subnodes can
         * be added).
         *
         * @since 2.0
         */
        interface ContainerElementNodeContextBuilder {

            /**
             * Defines the key the object is into the {@code Map}.
             *
             * @param key map key
             * @return a builder representing the current node
             */
            ContainerElementNodeBuilderDefinedContext atKey(Object key);

            /**
             * Defines the index the object is into the {@code List} or array.
             *
             * @param index index
             * @return a builder representing the current node
             */
            ContainerElementNodeBuilderDefinedContext atIndex(Integer index);

            /**
             * Adds a property node to the path the {@link ConstraintViolation}
             * will be associated to.
             *
             * {@code name} describes a single property. In particular,
             * dot (.) is not allowed.
             *
             * @param name property name
             * @return a builder representing node {@code name}
             * @throws IllegalArgumentException if the name is null
             */
            NodeBuilderCustomizableContext addPropertyNode(String name);

            /**
             * Adds a bean node (class-level) to the path the {@link ConstraintViolation}
             * will be associated to.
             * <p>
             * Note that bean nodes are always leaf nodes.
             *
             * @return a builder representing the bean node
             */
            LeafNodeBuilderCustomizableContext addBeanNode();

            /**
             * Adds a container element node to the path the {@link ConstraintViolation}
             * will be associated to.
             *
             * @param name the node name
             * @param containerType the type of the container
             * @param typeArgumentIndex the index of the type argument
             * @return a builder representing the container element node
             * @throws IllegalArgumentException if the index is not valid
             */
            ContainerElementNodeBuilderCustomizableContext addContainerElementNode(
                    String name, Class<?> containerType, Integer typeArgumentIndex);

            /**
             * Adds the new {@link ConstraintViolation} to be generated if the
             * constraint validator mark the value as invalid.
             * <p>
             * Methods of the {@code ConstraintViolationBuilder} instance this object
             * comes from and the constraint violation builder nested
             * objects throw {@code IllegalStateException} after this call.
             *
             * @return {@code ConstraintValidatorContext} instance the
             *         {@code ConstraintViolationBuilder} comes from
             */
            ConstraintValidatorContext addConstraintViolation();
        }
    }
}

/**
 * Instantiates a {@link ConstraintValidator} instance based off its class.
 * The {@code ConstraintValidatorFactory} is <b>not</b> responsible
 * for calling {@link ConstraintValidator#initialize(java.lang.annotation.Annotation)}.
 *
 * @author Dhanji R. Prasanna
 * @author Emmanuel Bernard
 * @author Hardy Ferentschik
 */
public interface ConstraintValidatorFactory {

    /**
     * @param key The class of the constraint validator to instantiate
     * @param <T> The type of the constraint validator to instantiate
     *
     * @return A new constraint validator instance of the specified class
     */
    <T extends ConstraintValidator<?, ?>> T getInstance(Class<T> key);

    /**
     * Signals {@code ConstraintValidatorFactory} that the instance is no longer
     * being used by the Bean Validation provider.
     *
     * @param instance validator being released
     *
     * @since 1.1
     */
    void releaseInstance(ConstraintValidator<?, ?> instance);
}

package javax.validation.valueextraction;

/**
 * Marks the type parameter of a generic container type to which a {@link ValueExtractor} is
 * tied or specifies the type of the wrapped element(s) of non-generic container types.
 * <p>
 * Must be given exactly once for a value extractor type.
 *
 * @author Gunnar Morling
 * @author Guillaume Smet
 *
 * @see ValueExtractor
 * @since 2.0
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE_USE)
@Documented
public @interface ExtractedValue {

    /**
     * The type of the value extracted by the {@link ValueExtractor}. If not set, the type
     * will be automatically inferred from the type argument of the parameterized type.
     * <p>
     * Used to define value extractors for non-generic wrapper types e.g.
     * {@link OptionalInt}.
     * <p>
     * May not be used when {@code ExtractedValue} is defined on the type parameter of
     * a generic container type. A {@code ValueExtractorDefinitionException} will be thrown
     * in this case.
     *
     * @return the type of the value extracted by the value extractor
     */
    Class<?> type() default void.class;
}

package javax.validation.valueextraction;

/**
 * Marks a {@link ValueExtractor} definition so that it is applied automatically when
 * detecting constraints declared on the container type supported by the extractor, causing
 * the constraints to be applied to the container's elements instead of the container.
 * <p>
 * If needed, this behavior can be changed per constraint using {@link Unwrapping.Skip},
 * causing the constraints to be applied to the container itself:
 *
 * <pre>
 * &#064;SomeConstraint(payload = Unwrapping.Skip.class)
 * SomeContainerType container;
 * </pre>
 *
 * @author Guillaume Smet
 * @since 2.0
 */
@Target({ TYPE })
@Retention(RUNTIME)
@Documented
public @interface UnwrapByDefault {

}

package javax.validation.groups;

/**
 * Default Bean Validation group.
 * <p>
 * Unless a list of groups is explicitly defined:
 * <ul>
 *     <li>constraints belong to the {@code Default} group</li>
 *     <li>validation applies to the {@code Default} group</li>
 * </ul>
 * Most structural constraints should belong to the default group.
 *
 * @author Emmanuel Bernard
 */
public interface Default {
}

/**
 * Validates bean instances. Implementations of this interface must be thread-safe.
 *
 * @author Emmanuel Bernard
 * @author Hardy Ferentschik
 * @author Gunnar Morling
 */
public interface Validator {

    /**
     * Validates all constraints on {@code object}.
     *
     * @param object object to validate
     * @param groups the group or list of groups targeted for validation (defaults to
     *        {@link Default})
     * @param <T> the type of the object to validate
     * @return constraint violations or an empty set if none
     * @throws IllegalArgumentException if object is {@code null}
     *         or if {@code null} is passed to the varargs groups
     * @throws ValidationException if a non recoverable error happens
     *         during the validation process
     */
    <T> Set<ConstraintViolation<T>> validate(T object, Class<?>... groups);

    /**
     * Validates all constraints placed on the property of {@code object}
     * named {@code propertyName}.
     *
     * @param object object to validate
     * @param propertyName property to validate (i.e. field and getter constraints)
     * @param groups the group or list of groups targeted for validation (defaults to
     *        {@link Default})
     * @param <T> the type of the object to validate
     * @return constraint violations or an empty set if none
     * @throws IllegalArgumentException if {@code object} is {@code null},
     *         if {@code propertyName} is {@code null}, empty or not a valid object property
     *         or if {@code null} is passed to the varargs groups
     * @throws ValidationException if a non recoverable error happens
     *         during the validation process
     */
    <T> Set<ConstraintViolation<T>> validateProperty(T object,
                                                     String propertyName,
                                                     Class<?>... groups);

    /**
     * Validates all constraints placed on the property named {@code propertyName}
     * of the class {@code beanType} would the property value be {@code value}.
     * <p>
     * {@link ConstraintViolation} objects return {@code null} for
     * {@link ConstraintViolation#getRootBean()} and
     * {@link ConstraintViolation#getLeafBean()}.
     *
     * @param beanType the bean type
     * @param propertyName property to validate
     * @param value property value to validate
     * @param groups the group or list of groups targeted for validation (defaults to
     *        {@link Default}).
     * @param <T> the type of the object to validate
     * @return constraint violations or an empty set if none
     * @throws IllegalArgumentException if {@code beanType} is {@code null},
     *         if {@code propertyName} is {@code null}, empty or not a valid object property
     *         or if {@code null} is passed to the varargs groups
     * @throws ValidationException if a non recoverable error happens
     *         during the validation process
     */
    <T> Set<ConstraintViolation<T>> validateValue(Class<T> beanType,
                                                  String propertyName,
                                                  Object value,
                                                  Class<?>... groups);

    /**
     * Returns the descriptor object describing bean constraints.
     * <p>
     * The returned object (and associated objects including
     * {@link ConstraintDescriptor}s) are immutable.
     *
     * @param clazz class or interface type evaluated
     * @return the bean descriptor for the specified class
     * @throws IllegalArgumentException if clazz is {@code null}
     * @throws ValidationException if a non recoverable error happens
     *         during the metadata discovery or if some
     *         constraints are invalid.
     */
    BeanDescriptor getConstraintsForClass(Class<?> clazz);

    /**
     * Returns an instance of the specified type allowing access to
     * provider-specific APIs.
     * <p>
     * If the Bean Validation provider implementation does not support
     * the specified class, {@link ValidationException} is thrown.
     *
     * @param type the class of the object to be returned
     * @param <T> the type of the object to be returned
     * @return an instance of the specified class
     * @throws ValidationException if the provider does not support the call
     */
    <T> T unwrap(Class<T> type);

    /**
     * Returns the contract for validating parameters and return values of methods
     * and constructors.
     *
     * @return contract for method and constructor validation
     *
     * @since 1.1
     */
    ExecutableValidator forExecutables();
}

/**
 * Describes a constraint violation. This object exposes the constraint
 * violation context as well as the message describing the violation.
 *
 * @param <T> the type of the root bean
 *
 * @author Emmanuel Bernard
 */
public interface ConstraintViolation<T> {

    /**
     * @return the interpolated error message for this constraint violation
     */
    String getMessage();

    /**
     * @return the non-interpolated error message for this constraint violation
     */
    String getMessageTemplate();

    /**
     * Returns the root bean being validated. For method validation, returns
     * the object the method is executed on.
     * <p>
     * Returns {@code null} when:
     * <ul>
     *     <li>the {@code ConstraintViolation} is returned after calling
     *     {@link Validator#validateValue(Class, String, Object, Class[])}</li>
     *     <li>the {@code ConstraintViolation} is returned after validating a
     *     constructor.</li>
     * </ul>
     *
     * @return the validated object, the object hosting the validated element or {@code null}
     */
    T getRootBean();

    /**
     * Returns the class of the root bean being validated.
     * For method validation, this is the object class the
     * method is executed on.
     * For constructor validation, this is the class the constructor
     * is declared on.
     *
     * @return the class of the root bean or of the object hosting the validated element
     */
    Class<T> getRootBeanClass();

    /**
     * Returns:
     * <ul>
     *     <li>the bean instance the constraint is applied on if it is
     *     a bean constraint</li>
     *     <li>the bean instance hosting the property the constraint
     *     is applied on if it is a property constraint or a container element constraint
     *     hosted on a property</li>
     *     <li>{@code null} when the {@code ConstraintViolation} is returned
     *     after calling {@link Validator#validateValue(Class, String, Object, Class[])}
     *     </li>
     *     <li>the object the method is executed on if it is
     *     a method parameter, cross-parameter or return value constraint or a
     *     container element constraint hosted on a method parameter or return value</li>
     *     <li>{@code null} if it is a constructor parameter or
     *     cross-parameter constraint or a container element constraint hosted on a
     *     constructor parameter</li>
     *     <li>the object the constructor has created if it is a
     *     constructor return value constraint</li>
     * </ul>
     *
     * @return the leaf bean
     */
    Object getLeafBean();

    /**
     * Returns an {@code Object[]} representing the constructor or method invocation
     * arguments if the {@code ConstraintViolation} is returned after validating the
     * method or constructor parameters.
     * Returns {@code null} otherwise.
     *
     * @return parameters of the method or constructor invocation or {@code null}
     *
     * @since 1.1
     */
    Object[] getExecutableParameters();

    /**
     * Returns the return value of the constructor or method invocation
     * if the {@code ConstraintViolation} is returned after validating the method
     * or constructor return value.
     * <p>
     * Returns {@code null} if the method has no return value.
     * Returns {@code null} otherwise.
     *
     * @return the method or constructor return value or {@code null}
     *
     * @since 1.1
     */
    Object getExecutableReturnValue();

    /**
     * @return the property path to the value from {@code rootBean}
     */
    Path getPropertyPath();

    /**
     * Returns the value failing to pass the constraint.
     * For cross-parameter constraints, an {@code Object[]} representing
     * the method invocation arguments is returned.
     *
     * @return the value failing to pass the constraint
     */
    Object getInvalidValue();

    /**
     * Returns the constraint metadata reported to fail.
     * The returned instance is immutable.
     *
     * @return constraint metadata
     */
    ConstraintDescriptor<?> getConstraintDescriptor();

    /**
     * Returns an instance of the specified type allowing access to
     * provider-specific APIs. If the Bean Validation provider
     * implementation does not support the specified class,
     * {@link ValidationException} is thrown.
     *
     * @param type the class of the object to be returned
     * @param <U> the type of the object to be returned
     * @return an instance of the specified class
     * @throws ValidationException if the provider does not support the call
     *
     * @since 1.1
     */
    <U> U unwrap(Class<U> type);
}

/**
 * Represents the navigation path from an object to another
 * in an object graph.
 * Each path element is represented by a {@code Node}.
 * <p>
 * The path corresponds to the succession of nodes
 * in the order they are returned by the {@code Iterator}.
 *
 * @author Emmanuel Bernard
 * @author Gunnar Morling
 * @author Guillaume Smet
 */
public interface Path extends Iterable<Path.Node> {

    /**
     * Returns a human-readable representation of this path.
     * <p>
     * Clients should not rely on any specific structure of the returned value. Instead they
     * should iterate through the path nodes and obtain any required information by calling
     * the methods on {@link Node} and its sub-types.
     *
     * @return a human-readable representation of this path
     * @since 2.0
     */
    @Override
    String toString();

    /**
     * Represents an element of a navigation path.
     */
    interface Node {

        /**
         * Returns the name of the element which the node represents:
         * <ul>
         *     <li>{@code null} if it is a leaf node which represents an entity / bean.
         *     In particular, the node representing the root object.</li>
         *     <li>The property name for a property.</li>
         *     <li>The method name for a method.</li>
         *     <li>The unqualified name of the type declaring the constructor
         *     for a constructor.</li>
         *     <li>The parameter named as defined by the {@link ParameterNameProvider}
         *     for a method or constructor parameter.</li>
         *     <li>The literal {@code <cross-parameter>} for a method or constructor
         *     cross-parameter.</li>
         *     <li>The literal {@code <return value>} for a method or constructor return
         *     value.</li>
         *     <li>The node name as defined by the {@link ValueExtractor} for a container
         *     element; specifically, the literal {@code <list element>} for elements
         *     stored in a list, the literal {@code <iterable element>} for elements
         *     stored in an {@code Iterable}, the literal {@code <map key>} for the keys
         *     stored in a {@code Map} and the literal {@code <map value>} for the values
         *     stored in a {@code Map}.
         * </ul>
         *
         * @return name of the element which the node represents
         */
        String getName();

        /**
         * @return {@code true} if the node represents an object contained in
         * a multi-valued container such as {@code Iterable} or {@code Map} or an array,
         * {@code false} otherwise
         */
        boolean isInIterable();

        /**
         * @return the index the node is placed in if contained in an array, a {@code List}
         *         or any other container supporting indexed access, {@code null} otherwise
         */
        Integer getIndex();

        /**
         * @return the key the node is placed in if contained in a {@code Map} or any
         *         other container supporting keyed access, {@code null} otherwise
         */
        Object getKey();

        /**
         * The kind of element represented by the node. The following relationship
         * between an {@link ElementKind} and its {@code Node} subtype exists:
         * <ul>
         *     <li>{@link ElementKind#BEAN}: {@link BeanNode}</li>
         *     <li>{@link ElementKind#PROPERTY}: {@link PropertyNode}</li>
         *     <li>{@link ElementKind#METHOD}: {@link MethodNode}</li>
         *     <li>{@link ElementKind#CONSTRUCTOR}: {@link ConstructorNode}</li>
         *     <li>{@link ElementKind#PARAMETER}: {@link ParameterNode}</li>
         *     <li>{@link ElementKind#CROSS_PARAMETER}: {@link CrossParameterNode}</li>
         *     <li>{@link ElementKind#RETURN_VALUE}: {@link ReturnValueNode}</li>
         *     <li>{@link ElementKind#CONTAINER_ELEMENT}: {@link ContainerElementNode}</li>
         * </ul>
         * <p>
         * This is useful to narrow down the {@code Node} type and access node specific
         * information:
         * <pre>
         * switch(node.getKind() {
         * case METHOD:
         *     name = node.getName();
         *     params = node.as(MethodNode.class).getParameterTypes();
         * case PARAMETER:
         *     index = node.as(ParameterNode.class).getParameterIndex();
         * [...]
         * }
         * </pre>
         *  @return the {@code ElementKind}
         *
         * @since 1.1
         */
        ElementKind getKind();

        /**
         * Narrows the type of this node down to the given type. The appropriate
         * type should be checked before by calling {@link #getKind()}.
         *
         * @param <T> the type to narrow down to
         * @param nodeType class object representing the descriptor type to narrow down to
         *                 to
         *
         * @return this node narrowed down to the given type.
         *
         * @throws ClassCastException if this node is not assignable to the type {@code T}
         * @since 1.1
         */
        <T extends Node> T as(Class<T> nodeType);

        /**
         * Returns a human-readable representation of this node.
         * <p>
         * Clients should not rely on any specific structure of the returned value. Instead
         * they should obtain any required information by calling the methods on this
         * interface and its sub-types.
         *
         * @return a human-readable representation of this node
         * @since 2.0
         */
        @Override
        String toString();
    }

    /**
     * Node representing a method.
     *
     * @since 1.1
     */
    interface MethodNode extends Node {

        /**
         * @return the list of parameter types
         */
        List<Class<?>> getParameterTypes();
    }

    /**
     * Node representing a constructor.
     *
     * @since 1.1
     */
    interface ConstructorNode extends Node {

        /**
         * @return the list of parameter types
         */
        List<Class<?>> getParameterTypes();
    }

    /**
     * Node representing the return value of a method or constructor.
     *
     * @since 1.1
     */
    interface ReturnValueNode extends Node {
    }

    /**
     * Node representing a parameter of a method or constructor.
     *
     * @since 1.1
     */
    interface ParameterNode extends Node {

        /**
         * @return the parameter index in the method or constructor definition
         */
        int getParameterIndex();
    }

    /**
     * Node representing the element holding cross-parameter constraints
     * of a method or constructor.
     *
     * @since 1.1
     */
    interface CrossParameterNode extends Node {
    }

    /**
     * Node representing a bean.
     *
     * @since 1.1
     */
    interface BeanNode extends Node {

        /**
         * @return the type of the container the node is placed in, if contained in a
         * container type such as {@code Optional}, {@code List} or {@code Map},
         * {@code null} otherwise
         *
         * @since 2.0
         */
        Class<?> getContainerClass();

        /**
         * @return the index of the type argument affected by the violated constraint, if
         * contained in a generic container type such as {@code Optional}, {@code List} or
         * {@code Map}.
         *
         * @since 2.0
         */
        Integer getTypeArgumentIndex();
    }

    /**
     * Node representing a property.
     *
     * @since 1.1
     */
    interface PropertyNode extends Node {

        /**
         * @return the type of the container the node is placed in, if contained in a
         * container type such as {@code Optional}, {@code List} or {@code Map},
         * {@code null} otherwise
         *
         * @since 2.0
         */
        Class<?> getContainerClass();

        /**
         * @return the index of the type argument affected by the violated constraint, if
         * contained in a generic container type such as {@code Optional}, {@code List} or
         * {@code Map}, {@code null} otherwise
         *
         * @since 2.0
         */
        Integer getTypeArgumentIndex();
    }

    /**
     * Node representing an element in a generic container such as {@code Optional},
     * {@code List} or {@code Map}.
     *
     * @since 2.0
     */
    interface ContainerElementNode extends Node {

        /**
         * @return the type of the container the node is placed in
         */
        Class<?> getContainerClass();

        /**
         * @return the index of the type argument affected by the violated constraint
         */
        Integer getTypeArgumentIndex();
    }
}