Jakarta Validation 3.1

https://jakarta.ee/specifications/bean-validation/3.1/
Admin
Jakarta Validation defines a metadata model and API for JavaBean and method validation, with this...
Tokens:113,435
Snippets:900
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### META-INF/validation.xml Configuration Example

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

This snippet shows an example of the META-INF/validation.xml file, demonstrating how to configure the default provider, message interpolator, and executable validation settings.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<validation-config
        xmlns="https://jakarta.ee/xml/ns/validation/configuration"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://jakarta.ee/xml/ns/validation/configuration
            https://jakarta.ee/xml/ns/validation/configuration/validation-configuration-3.0.xsd"
        version="3.0">
    <default-provider>com.acme.ACMEProvider</default-provider>
    <message-interpolator>com.acme.ACMEAwareMessageInterpolator</message-interpolator>

    <executable-validation>
        <default-validated-executable-types>
            <executable-type>NONE</executable-type>
        </default-validated-executable-types>
    </executable-validation>


```

--------------------------------

### Method-Level Declaration Example

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates how to declare method-level constraints, including parameter types, return value validation, and cross-parameter constraints using XML.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<constraint-mappings
        xmlns="https://jakarta.ee/xml/ns/validation/mapping"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://jakarta.ee/xml/ns/validation/mapping
            https://jakarta.ee/xml/ns/validation/mapping/validation-mapping-3.0.xsd"
        version="3.0">
    <default-package>com.acme.app.domain</default-package>
    <bean class="Customer" ignore-annotations="false">
        <method name="update" ignore-annotations="true">
            <parameter type="java.lang.String">
                [...]
            </parameter>
            <parameter type="int">
                <valid/>
                [...]
            </parameter>
            <parameter type="long" ignore-annotations="false"/>
            <cross-parameter ignore-annotations="false">
                [...]
            </cross-parameter>
            <return-value>
                <valid/>
                [...]
            </return-value>
            [...]
        </method>

    </bean>
</constraint-mappings>
```

--------------------------------

### Provider Specific Configuration Interface

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Example of a provider-specific Configuration sub-interface, linking the provider to its configuration. This interface can host provider-specific configuration methods.

```java
/**
 * Unique identifier of the ACME provider
 * also hosts some provider specific configuration methods
 */
public interface ACMEConfiguration
    extends Configuration<ACMEConfiguration> {

    /**
     * Enables constraints implementation dynamic reloading when using ACME
     * default to false
     */
    ACMEConfiguration enableDynamicReloading(boolean);

}

/**
 * ACME validation provider
 * Note how ACMEConfiguration and ACMEProvider are linked together
 * via the generic parameter.
 */

```

--------------------------------

### Container Element Constraints Examples

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates applying constraints like @Email, @NotNull, @Size, and @NotBlank to elements within List, Optional, and Map types.

```java
private List<@Email String> emails;

public Optional<@Email String> getEmail() {
    [...]
}

public Map<@NotNull String, @ValidAddress Address> getAddressesByType() {
    [...]
}

public List<@NotBlank String> getMatchingRecords(List<@NotNull @Size(max=20) String> searchTerms) {
    [...]
}
```

--------------------------------

### Severity Payload Example

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates using custom Payload classes (Info, Error) to associate severity levels with constraints.

```Java
package com.acme.severity;

public class Severity {
    public static class Info implements Payload {};
    public static class Error implements Payload {};
}

public class Address {
    @NotNull(message="would be nice if we had one", payload=Severity.Info.class)
    public String getZipCode() { [...] }

    @NotNull(message="the city is mandatory", payload=Severity.Error.class)
    String getCity() { [...] }
}
```

--------------------------------

### Object Graph Validation Example

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Illustrates the validation paths and ignored cascading operations in a complex object graph to prevent infinite loops. This is a conceptual example showing the logic.

```text
#assuming the following object graph

Order -(lines)→ Orderline1
Order -(lines)→ Orderline2
Orderline1 -(order)→ Order
Orderline2 -(order)→ Order
Order -(customer)→ User
Order -(shippingAddress)→ Address1
Order -(billingAddress)→ Address2
Address1 -(inhabitant)→ User
Address2 -(inhabitant)→ User
User -(addresses)→ Address1
User -(addresses)→ Address2

#validation branches are as followed
Order -(lines)→ Orderline1
  - order is ignored: Order is already present in the branch

Order -(lines)→ Orderline2
  - order is ignored: Order is already present in the branch

Order -(customer)→ User -(addresses)→ Address1
  - inhabitant is ignored: User is already present in the branch

Order -(customer)→ User -(addresses)→ Address2
  - inhabitant is ignored: User is already present in the branch

Order -(shippingAddress)→ Address1 -(inhabitant)→ User
  - addresses to Address1 is ignored: Address1 is already present in the branch

Order -(shippingAddress)→ Address1 -(inhabitant)→ User -(addresses)→ Address2
  - inhabitant is ignored: User is already present in the branch

Order -(billingAddress)→ Address2 -(inhabitant)→ User
  - addresses to Address2 is ignored: Address2 is already present in the branch

Order -(billingAddress)→ Address2 -(inhabitant)→ User -(addresses)→ Address1
  - inhabitant is ignored: User is already present in the branch
```

--------------------------------

### META-INF/validation.xml Configuration Example

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

This snippet shows a typical META-INF/validation.xml configuration. It includes mapping constraint definitions from external XML files and setting custom validation properties.

```xml
<validation-config>
    <constraint-mapping>META-INF/validation/order-constraints.xml</constraint-mapping>
    <constraint-mapping>META-INF/validation/catalog-constraints.xml</constraint-mapping>
    <constraint-mapping>META-INF/validation/customer-constraints.xml</constraint-mapping>

    <property name="com.acme.validation.logging">WARN</property>
    <property name="com.acme.validation.safetyChecking">failOnError</property>

</validation-config>
```

--------------------------------

### Usage Example of Group Sequence

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates how to use `@GroupSequence` to define an ordered validation flow. Constraints in `HighLevelCoherence` are only evaluated if `Default` constraints pass.

```java
@ZipCodeCoherenceChecker(groups = Address.HighLevelCoherence.class)
public class Address {
    @NotNull @Size(max = 50)
    private String street1;

    @NotNull @ZipCode
    private String zipCode;

    @NotNull @Size(max = 30)
    private String city;

    /**
     * check coherence on the overall object
     * Needs basic checking to be green first
     */
    public interface HighLevelCoherence {}

    /**
     * check both basic constraints and high level ones.
     * high level constraints are not checked if basic constraints fail
     */
    @GroupSequence({Default.class, HighLevelCoherence.class})
    public interface Complete {}
}
```

--------------------------------

### Interface/Group Hosting Constraints for Auditable

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

This example demonstrates how to define an interface 'Auditable' which implicitly groups constraints. Constraints within this interface, when part of the Default group, are associated with the 'Auditable' group.

```java
/**
 * Auditable object contract
 */
public interface Auditable {
    @NotNull String getCreationDate();
    @NotNull String getLastUpdate();
    @NotNull String getLastModifier();
    @NotNull String getLastReader();
}

/**
 * Represents an order in the system
 */
public class Order implements Auditable {
    private String creationDate;
    private String lastUpdate;
    private String lastModifier;
    private String lastReader;

    private String orderNumber;

    public String getCreationDate() {
        return this.creationDate;
    }

    public String getLastUpdate() {
        return this.lastUpdate;
    }

    public String getLastModifier() {
        return this.lastModifier;
    }

    public String getLastReader() {
        return this.lastReader;
    }

    @NotNull @Size(min=10, max=10)
    public String getOrderNumber() {
        return this.orderNumber;
    }
}
```

--------------------------------

### Library and User Class Definitions

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Defines the Library and User classes with various constraints for method and constructor parameters, and return values. These are assumed for the following examples.

```java
public class Library {

    @PublicLibrary
    public Library() {
        [...]
    }

    public Library(@NotNull List<@Valid Book> books) {
        [...]
    }

    public void addBook(@NotNull @Valid Book book) {
        [...]
    }

    @Valid public Map<Author, Book> getMostPopularBookPerAuthor() {
        [...]
    }
}

public class User {

    @OldAndNewPasswordsDifferent
    public void renewPassword(String oldPassword, String newPassword, String retypedNewPassword);
}

Library library = new Library();
author.setLastName("Doe");
```

--------------------------------

### Define a Composed Constraint with @ReportAsSingleViolation

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

This example demonstrates how to use `@ReportAsSingleViolation` on a composed constraint. If any composing constraint fails, only a single error report for the composed constraint is generated.

```java
@Pattern(regexp = "[0-9]*")
@Size(min = 5, max = 5)
@ReportAsSingleViolation
@Constraint(validatedBy = FrenchZipCodeValidator.class)
@Documented
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
@Retention(RUNTIME)
public @interface FrenchZipCode {

    String message() default "Wrong zip code";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};

    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
    @Retention(RUNTIME)
    @Documented
    @interface List {
        FrenchZipCode[] value();
    }
}
```

--------------------------------

### Configuration API Methods

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

This section details the methods available on the Configuration interface for retrieving various validation-related components and properties. These methods allow for programmatic access and inspection of the validation setup.

```APIDOC
## getValueExtractors

### Description
Retrieves the set of value extractors configured for this validation setup. These extractors are used to extract values from objects for validation purposes. Programmatic configuration takes precedence over XML and service loader configurations.

### Method
GET

### Endpoint
N/A (Programmatic API)

### Parameters
None

### Response
#### Success Response (200)
- **Set<ValueExtractor<?>>** - A set of configured value extractors. Returns an empty set if none are configured, but never null.

### Response Example
```json
{
  "example": "[ValueExtractor1, ValueExtractor2]"
}
```

## getConstraintValidatorFactory

### Description
Retrieves the constraint validator factory. This factory is responsible for creating instances of constraint validators. The factory can be set programmatically, defined in `META-INF/validation.xml`, or be null if undefined.

### Method
GET

### Endpoint
N/A (Programmatic API)

### Parameters
None

### Response
#### Success Response (200)
- **ConstraintValidatorFactory** - The configured constraint validator factory instance, or null if not defined.

### Response Example
```json
{
  "example": "ConstraintValidatorFactoryImpl"
}
```

## getTraversableResolver

### Description
Retrieves the traversable resolver. This resolver determines how bean traversal is handled during validation. It can be set programmatically, defined in `META-INF/validation.xml`, or be null if undefined.

### Method
GET

### Endpoint
N/A (Programmatic API)

### Parameters
None

### Response
#### Success Response (200)
- **TraversableResolver** - The configured traversable resolver instance, or null if not defined.

### Response Example
```json
{
  "example": "TraversableResolverImpl"
}
```

## getParameterNameProvider

### Description
Retrieves the parameter name provider. This provider is used to obtain parameter names, particularly for method validation. It can be set programmatically, defined in `META-INF/validation.xml`, or be null if undefined.

### Method
GET

### Endpoint
N/A (Programmatic API)

### Parameters
None

### Response
#### Success Response (200)
- **ParameterNameProvider** - The configured parameter name provider instance, or null if not defined.

### Response Example
```json
{
  "example": "ParameterNameProviderImpl"
}
```

## getClockProvider

### Description
Retrieves the clock provider. This provider is used for obtaining the current time, often relevant for date/time related constraints. It can be set programmatically, defined in `META-INF/validation.xml`, or be null if undefined.

### Method
GET

### Endpoint
N/A (Programmatic API)

### Parameters
None

### Response
#### Success Response (200)
- **ClockProvider** - The configured clock provider instance, or null if not defined.

### Response Example
```json
{
  "example": "ClockProviderImpl"
}
```

## getProperties

### Description
Retrieves a map of non type-safe custom properties. These properties can be set programmatically or defined in `META-INF/validation.xml`. Programmatically defined properties take precedence over XML configurations.

### Method
GET

### Endpoint
N/A (Programmatic API)

### Parameters
None

### Response
#### Success Response (200)
- **Map<String, String>** - A map where keys are property names and values are their corresponding string values.

### Response Example
```json
{
  "example": {
    "property1": "value1",
    "property2": "value2"
  }
}
```
```

--------------------------------

### Property Path for @AvailableInStore on Book

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Illustrates the property path for the @AvailableInStore constraint on the Book class. The path starts with a BeanNode.

```java
BeanNode(name=null, inIterable=false, index=null, key=null, containerClass=null, typeArgumentIndex=null, kind=ElementKind.BEAN)
```

--------------------------------

### Create Multiple ValidatorFactories from Configuration

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates creating multiple ValidatorFactory instances from a single Configuration object, applying different customizations to each. This allows for flexible validation setups.

```java
Configuration<?> configuration = [...];
ValidatorFactory factory1 = configuration
              .messageInterpolator( new WBMessageInterpolator() )
              .buildValidatorFactory();

ValidatorFactory factory2 = configuration
              .traversableResolver( new JPAAwareTraversableResolver() )
              .buildValidatorFactory();
```

--------------------------------

### Example ConstraintValidator Declaration

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates how to declare a constraint annotation with multiple ConstraintValidator implementations. Each validator targets a specific type or a set of types.

```java
@Constraint(validatedBy= {
    SizeValidatorForCollection.class,
    SizeValidatorForSet.class,
    SizeValidatorForSerializable.class
 })
public @interface Size { [...] }
```

--------------------------------

### Use Inheritance and Composite Constraints

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

This example demonstrates how constraints can be applied to an interface and inherited by its implementing classes. The @NonEmpty constraint is applied to getters in the Person interface.

```java
public interface Person {
    @NonEmpty
    String getFirstName();

    String getMiddleName();

    @NonEmpty
    String getLastName();
}

public class Customer implements Person {
    private String firstName;
    private String middleName;

```

--------------------------------

### Use Specific Provider and Add Configuration

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Selects a specific Jakarta Validation provider (ACMEProvider) and configures it programmatically with provider-specific properties. This example demonstrates adding custom constraints.

```java
ValidatorFactory factory = Validation
       .byProvider( ACMEProvider.class )  //chose a specific provider
       .configure()
          .messageInterpolator( new ContainerMessageInterpolator() ) //default configuration option
          .addConstraint(Address.class, customConstraintDescriptor) //ACME specific method
          .buildValidatorFactory();

//same initialization decomposing calls
ACMEConfiguration acmeConfiguration = Validation
       .byProvider( ACMEProvider.class )
       .configure();

ValidatorFactory factory = acmeConfiguration
          .messageInterpolator( new ContainerMessageInterpolator() ) //default configuration option
          .addConstraint(Address.class, customConstraintDescriptor) //ACME specific method
          .buildValidatorFactory();

/**
 * ACME specific validator configuration and configuration options
 */
public interface ACMEConfiguration extends Configuration<ACMEConfiguration> {
    /**
     * Programmatically add constraints. Specific to the ACME provider.
     */
    ACMEConfiguration addConstraint(Class<?> entity,
                                    ACMEConstraintDescriptor constraintDescriptor);
}

/**
 * ACME validation provider
 * Note how ACMEConfiguration and ACMEProvider are linked together
 * via the generic parameter.
 */
public class ACMEProvider implements ValidationProvider<ACMEConfiguration> {
    [...]
}
```

--------------------------------

### Object Model Definition for Examples

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Defines the Java classes Author, Book, Review, Category, and Library with various Jakarta Validation constraints. This model is used to illustrate property path generation.

```java
@SecurityChecking
public class Author {
    private String firstName;

    @NonEmpty(message="lastname must not be null")
    private String lastName;

    @Size(max=30)
    private String company;

    [...] 

    @OldAndNewPasswordsDifferent
    @NewPasswordsIdentical
    public void renewPassword(
            String oldPassword, String newPassword, String retypedNewPassword) {
        [...] 
    }
}

@AvailableInStore(groups={Availability.class})
public class Book {
    @NonEmpty(groups={FirstLevelCheck.class, Default.class})
    private String title;

    @Valid
    @NotNull
    private List<Author> authors;

    @Valid
    private Map<String, Review> reviewsPerSource;

    @Valid
    private Review pickedReview;

    private List<@NotBlank String> tags;

    private Map<Integer, List<@NotBlank String>> tagsByChapter;

    private List<@Valid Category> categories;

    private Map<Integer, List<@Valid Author>> authorsByChapter;

    [...] 
}

public class Review {

    @Min(0)
    private int rating;
    [...] 
}

public class Category {

    @Size(min=3)
    private String name;

    // [...] 
}

public class Library {

    public Library(@NotNull String name, @NotNull String location) {
        [...] 
    }

    public void addBook(@NotNull @Valid Book book) {
        [...] 
    }

    public void addAllBooks(@NotNull List<@Valid Book> books) {
        [...] 
    }

    @NotNull public String getLocation() {
        [...] 
    }

    public Map<Author, @Valid Book> getMostPopularBookPerAuthor() {
        [...] 
    }
}
```

--------------------------------

### ACME Provider Specific Configuration

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Example of a provider-specific configuration interface for the ACME provider. It extends the generic Configuration and adds a custom method to enable dynamic reloading.

```java
/**
 * Unique identifier of the ACME provider
 * also hosts some provider specific configuration methods
 */
public interface ACMEConfiguration
    extends Configuration<ACMEConfiguration> {

    /**
     * Enables constraints implementation dynamic reloading when using ACME
     * default to false
     */
    ACMEConfiguration enableDynamicReloading(boolean);

}
```

--------------------------------

### Method Parameter Validation Example

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates method validation for an `AddressService` class. It shows how Jakarta Bean Validation handles constraints on method parameters, including cascaded validation and reachability checks.

```java
public class AddressService {
    public void persistAddress(@NotNull @Valid Address address) {
        [...] 
    }
}
```

--------------------------------

### Constructor Return Value Constraint Violation Example

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates assertions for a ConstraintViolation resulting from a constructor return value validation. This is useful for verifying the details of violations related to newly created objects.

```java
assert "must not be null".equals( constraintViolation.getMessage() );

assert null == constraintViolation.getRootBean();
assert Library.class == constraintViolation.getRootBeanClass();
assert null == constraintViolation.getLeafBean();
assert null == constraintViolation.getInvalidValue();

assert new Object[]{ null }.equals( constraintViolation.getExecutableParameters() );
assert null == constraintViolation.getExecutableReturnValue();

Iterator<Node> nodeIter = constraintViolation.getPropertyPath().iterator();

Node node = nodeIter.next();
assert "Library".equals( node.getName() );
assert ElementKind.CONSTRUCTOR.equals( node.getKind() );

node = nodeIter.next();
//assuming the default parameter name provider is used and parameter names can
//be obtained
assert "books".equals( node.getName() );
assert ElementKind.PARAMETER.equals( node.getKind() );

assert false == nodeIter.hasNext();
```

--------------------------------

### Custom Validator for @Past Temporal Constraint

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

This example demonstrates a custom validator for the @Past constraint, specifically for ZonedDateTime. It utilizes the ClockProvider from the ConstraintValidatorContext to get the current time for comparison.

```java
/**
 * Validates that the given {@link ZonedDateTime} is in the past.
 */
public class PastValidatorForZonedDateTime implements ConstraintValidator<Past, ZonedDateTime> {

    @Override
    public boolean isValid(ZonedDateTime value, ConstraintValidatorContext context) {
        if ( value == null ) {
            return true;
        }

        ZonedDateTime now = ZonedDateTime.now( context.getClockProvider().getClock() );

        return value.isBefore( now );
    }
}
```

--------------------------------

### Cross-Parameter ConstraintValidator Example

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Example of a ConstraintValidator implementation that targets cross-parameters. The validator must accept Object[] as the validated type.

```java
@SupportedValidationTarget(ValidationTarget.PARAMETERS)
public class ScriptAssertValidator implements ConstraintValidator<ScriptAssert,Object[]> {
```

--------------------------------

### Configuration Interface Methods

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Provides methods to retrieve default ClockProvider, bootstrap configuration, and to build a ValidatorFactory.

```java
ClockProvider getDefaultClockProvider();

    /**
     * Returns configuration information stored in the {@code META-INF/validation.xml} file.
     * <p>
     * <b>Note</b>:
     * <br>
     * Implementations are encouraged to lazily build this object to delay parsing.
     *
     * @return returns an instance of {@link BootstrapConfiguration}; this method never
     *         returns {@code null}; if there is no {@code META-INF/validation.xml} the
     *         different getters of the returned instance will return {@code null}
     *         respectively an empty set or map
     *
     * @since 1.1
     */
    BootstrapConfiguration getBootstrapConfiguration();

    /**
     * Build a {@link ValidatorFactory} implementation.
     *
     * @return the {@code ValidatorFactory}
     * @throws ValidationException if the {@code ValidatorFactory} cannot be built
     */
    ValidatorFactory buildValidatorFactory();
```

--------------------------------

### Method Return Value Constraint Violation Example

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Illustrates assertions for a ConstraintViolation related to a method's return value. This example is helpful for debugging and understanding violations in method outputs.

```java
//assuming an english locale, the interpolated message is returned
assert "may not be null or empty".equals( constraintViolation.getMessage() );

assert library == constraintViolation.getRootBean();
assert Library.class == constraintViolation.getRootBeanClass();
assert book == constraintViolation.getLeafBean();
assert book.getTitle().equals( constraintViolation.getInvalidValue() );

assert null == constraintViolation.getExecutableParameters();
assert mostPopularBookPerAuthor == constraintViolation.getExecutableReturnValue();

Iterator<Node> nodeIter = constraintViolation.getPropertyPath().iterator();

Node node = nodeIter.next();
assert "getMostPopularBookPerAuthor".equals( node.getName() );
assert ElementKind.METHOD.equals( node.getKind() );

node = nodeIter.next();
assert "<return value>" == node.getName();
assert ElementKind.RETURN_VALUE.equals( node.getKind() );

node = nodeIter.next();
assert "title".equals( node.getName() );
assert ElementKind.PROPERTY.equals( node.getKind() );
assert author.equals( node.getKey() );
assert true == node.isInIterable();

assert false == nodeIter.hasNext();
```

--------------------------------

### Configuration Interface Methods

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Provides methods to retrieve the default ClockProvider, bootstrap configuration from validation.xml, and to build a ValidatorFactory.

```APIDOC
## Configuration Interface

### Description
This interface provides methods for accessing default configuration elements and building a ValidatorFactory.

### Methods

- **getDefaultClockProvider()**
  - Returns the default {@code ClockProvider} implementation compliant with the specification.
  - @since 2.0

- **getBootstrapConfiguration()**
  - Returns configuration information stored in the {@code META-INF/validation.xml} file.
  - Implementations are encouraged to lazily build this object to delay parsing.
  - @return an instance of {@link BootstrapConfiguration}; this method never returns {@code null}; if there is no {@code META-INF/validation.xml} the different getters of the returned instance will return {@code null} respectively an empty set or map
  - @since 1.1

- **buildValidatorFactory()**
  - Builds a {@link ValidatorFactory} implementation.
  - @return the {@code ValidatorFactory}
  - @throws ValidationException if the {@code ValidatorFactory} cannot be built
```

--------------------------------

### LegalEntity Interface Definition

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Defines the LegalEntity interface with a method to get roles.

```java
public interface LegalEntity {

    Iterable<@NotNull String> getRoles();
}
```

--------------------------------

### Validate Object Example

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Validates the entire Address object, expecting two constraint violations.

```java
validator.validate(address).size() == 2
```

--------------------------------

### ACMEProvider Implementation

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Example of a custom ValidationProvider implementation. The generic type parameter allows for provider-specific configuration.

```java
public class ACMEProvider implements ValidationProvider<ACMEConfiguration> {
    [...]
}
```

--------------------------------

### BootstrapConfiguration Interface Methods

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Details methods for accessing user-specified default configuration from META-INF/validation.xml.

```APIDOC
## BootstrapConfiguration Interface

### Description
Represents the user-specified default configuration in {@code META-INF/validation.xml}. Modifications to returned objects do not have any effect; use methods on {@link Configuration} to apply modifications.

### Methods

- **getDefaultProviderClassName()**
  - Returns the class name of the {@link ValidationProvider} implementation or {@code null} if none is specified.

- **getConstraintValidatorFactoryClassName()**
  - Returns the class name of the {@link ConstraintValidatorFactory} implementation or {@code null} if none is specified.

- **getMessageInterpolatorClassName()**
  - Returns the class name of the {@link MessageInterpolator} implementation or {@code null} if none is specified.

- **getTraversableResolverClassName()**
  - Returns the class name of the {@link TraversableResolver} implementation or {@code null} if none is specified.

- **getParameterNameProviderClassName()**
  - Returns the class name of the {@link ParameterNameProvider} implementation or {@code null} if none is specified.

- **getClockProviderClassName()**
  - Returns the class name of the {@link ClockProvider} implementation or {@code null} if none is specified.
  - @since 2.0

- **getValueExtractorClassNames()**
  - Returns the class names of {@link ValueExtractor}s.
  - @return the value extractor class names or an empty set if none are specified
  - @since 2.0

- **getConstraintMappingResourcePaths()**
  - Returns a set of resource paths pointing to XML constraint mapping files.
  - The set is empty if none are specified.
  - @return set of constraint mapping resource paths

- **isExecutableValidationEnabled()**
  - Returns {@code true} if the validation execution is explicitly marked as enabled or if it is left undefined.
  - @return whether validation execution is globally enabled

- **getDefaultValidatedExecutableTypes()**
  - Returns the set of executable types that should be considered unless explicitly overridden via {@link ValidateOnExecution}.
  - Returns a set containing {@link ExecutableType#CONSTRUCTORS} and {@link ExecutableType#NON_GETTER_METHODS} if unspecified in the configuration.
  - @return set of validated executable types

- **getProperties()**
  - Returns properties as a map of string based key/value pairs.
  - The map is empty if no property has been specified.
  - @return the properties map
```

--------------------------------

### Select Method and Constructor Constraints using ConstraintFinder

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates using the ConstraintFinder API to retrieve parameter, cross-parameter, and return value constraints for methods and constructors, considering both local and inherited constraints.

```java
public class User {

    public User(@Size(max=50) String name) {
        [...]
    }

    @PasswordParametersMatch
    @NotNull
    public String resetPassword(
        @NotNull @Size(min=8) String password,
        @NotNull @Size(min=8) String confirmation) {
        [...]
    }
}

public class Customer extends User {

    public Customer(@NotNull String name) {
        [...]
    }

    @Size(min=8)
    public String resetPassword(String password, String confirmation) {
        [...]
    }
}

MethodDescriptor methodDescriptor = validator
    .getConstraintsForClass( Customer.class )
    .getConstraintsForMethod( "resetPassword", String.class, String.class );

//one cross-parameter constraint
assert 1 == methodDescriptor.getCrossParameterDescriptor().getConstraintDescriptors().size();

//one local return value constraint
assert 1 == methodDescriptor.getReturnValueDescriptor()
    .findConstraints()
    .lookingAt( Scope.LOCAL_ELEMENT )
    .getConstraintDescriptors()
    .size();

//two return value constraints in the complete hierarchy
assert 2 == methodDescriptor.getReturnValueDescriptor()
    .findConstraints()
    .lookingAt( Scope.HIERARCHY )
    .getConstraintDescriptors()
    .size();

//two parameter constraints, defined on overridden method
assert 2 == methodDescriptor.getParameterDescriptors()
    .get( 0 )
    .getConstraintDescriptors()
    .size();

ConstructorDescriptor constructorDescriptor = validator
    .getConstraintsForClass( Customer.class )
    .getConstraintsForConstructor( String.class );

//one parameter constraint; constraints from super constructor don't apply
assert 1 == constructorDescriptor.getParameterDescriptors()
    .get( 0 )
    .findConstraints()
    .lookingAt( Scope.HIERARCHY )
    .getConstraintDescriptors()
    .size();
```

--------------------------------

### Validate Property Example

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Validates only the 'city' property of the Address object, expecting one constraint violation.

```java
validator.validateProperty(address, "city").size() == 1
```

--------------------------------

### Valid ConstraintValidator Definitions

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Examples of correctly implemented ConstraintValidator interfaces for various types and validation targets.

```java
public class SizeValidatorForString implements ConstraintValidator<Size, String> {
    [...] 
}
```

```java
public class SizeValidatorForCollection implements ConstraintValidator<Size, Collection> {
    [...] 
}
```

```java
public class SizeValidatorForCollection implements ConstraintValidator<Size, Collection<?>> {
    [...] 
}
```

```java
@SupportedValidationTarget(ValidationTarget.PARAMETERS)
public class DateParametersConsistentValidator
    implements ConstraintValidator<DateParametersConsistent, Object[]> {
    [...] 
}
```

```java
@SupportedValidationTarget({ValidationTarget.ANNOTATED_ELEMENT, ValidationTarget.PARAMETERS})
public class ELScriptValidator implements ConstraintValidator<ELScript, Object> {
    [...] 
}
```

--------------------------------

### Custom Serializable Collection Interface

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Defines a custom interface that extends both Serializable and Collection, used in resolution examples.

```java
public interface SerializableCollection extends Serializable, Collection {
}
```

--------------------------------

### Validate Value Example

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Validates a potential value for the 'city' property without validating the object itself, expecting no constraint violations.

```java
validator.validateValue(Address.class, "city", "Paris").size() == 0
```

--------------------------------

### Declare Multiple Constraints Using Repeatable Annotations

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

This example demonstrates how to declare multiple `@ZipCode` constraints on the `zipCode` field of an `Address` class. Each constraint is applied with different groups and error messages, leveraging the repeatable nature of the annotation.

```java
public class Address {
    @ZipCode(countryCode = "fr", groups = Default.class, message = "zip code is not valid")
    @ZipCode(
        countryCode = "fr",
        groups = SuperUser.class,
        message = "zip code invalid. Requires overriding before saving."
    )
    private String zipCode;
}
```

--------------------------------

### Invalid ConstraintValidator Definitions

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Examples illustrating common mistakes when implementing ConstraintValidator interfaces, such as incorrect use of parameterized types.

```java
public class SizeValidatorForString implements ConstraintValidator<Size, Collection<String>> {
    [...] 
}
```

```java
public class SizeValidatorForCollection implements ConstraintValidator<Size, Collection<? extends Address>> {
    [...] 
}
```

```java
@SupportedValidationTarget(ValidationTarget.PARAMETERS)
public class NumberPositiveValidator implements ConstraintValidator<NumberPositive, Number> {
    [...] 
}
```

--------------------------------

### BootstrapConfiguration Interface Methods

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Defines methods to access user-specified default configuration values from META-INF/validation.xml, including provider class name, constraint validator factory, message interpolator, traversable resolver, parameter name provider, clock provider, value extractors, constraint mapping resources, executable validation settings, and properties.

```java
String getDefaultProviderClassName();

    /**
     * Class name of the {@link ConstraintValidatorFactory} implementation
     * or {@code null} if none is specified.
     *
     * @return constraint validator factory class name or {@code null}
     */
    String getConstraintValidatorFactoryClassName();

    /**
     * Class name of the {@link MessageInterpolator} implementation
     * or {@code null} if none is specified.
     *
     * @return message interpolator class name or {@code null}
     */
    String getMessageInterpolatorClassName();

    /**
     * Class name of the {@link TraversableResolver} implementation
     * or {@code null} if none is specified.
     *
     * @return traversable resolver class name or {@code null}
     */
    String getTraversableResolverClassName();

    /**
     * Class name of the {@link ParameterNameProvider} implementation
     * or {@code null} if none is specified.
     *
     * @return parameter name provider class name or {@code null}
     */
    String getParameterNameProviderClassName();

    /**
     * Class name of the {@link ClockProvider} implementation or
     * {@code null} if none is specified.
     *
     * @return clock provider class name or {@code null}
     *
     * @since 2.0
     */
    String getClockProviderClassName();

    /**
     * Returns the class names of {@link ValueExtractor}s.
     *
     * @return the value extractor class names or an empty set if none are specified
     * @since 2.0
     */
    Set<String> getValueExtractorClassNames();

    /**
     * Returns a set of resource paths pointing to XML constraint mapping files.
     * The set is empty if none are specified.
     *
     * @return set of constraint mapping resource paths
     */
    Set<String> getConstraintMappingResourcePaths();

    /**
     * Returns true if the validation execution is explicitly marked as enabled
     * or if it is left undefined.
     *
     * @return whether validation execution is globally enabled
     */
    boolean isExecutableValidationEnabled();

    /**
     * Returns the set of executable types that should be considered
     * unless explicitly overridden via {@link ValidateOnExecution}.
     * <p>
     * Returns a set containing {@link ExecutableType#CONSTRUCTORS} and
     * {@link ExecutableType#NON_GETTER_METHODS} if unspecified in the configuration.
     *
     * @return set of validated executable types
     */
    Set<ExecutableType> getDefaultValidatedExecutableTypes();

    /**
     * Returns properties as a map of string based key/value pairs.
     * The map is empty if no property has been specified.
     *
     * @return the properties map
     */
    Map<String, String> getProperties();
```

--------------------------------

### Default Provider Bootstrap

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Initiates the bootstrap process for the default Jakarta Validation provider.

```APIDOC
## public static GenericBootstrap byDefaultProvider()

### Description
Returns a `GenericBootstrap` instance that can be used to configure the default Jakarta Validation provider.

### Method
GET

### Endpoint
N/A (Programmatic API)

### Parameters
None

### Response
#### Success Response
- **GenericBootstrap** (GenericBootstrap) - An instance of `GenericBootstrap` for further configuration.

#### Response Example
```java
GenericBootstrap bootstrap = Validation.byDefaultProvider();
```
```

--------------------------------

### Example ListValueExtractor Implementation

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates a concrete implementation of ValueExtractor for a List. It iterates through the list elements and passes each to the ValueReceiver using the indexedValue method.

```java
public class ListValueExtractor implements
        ValueExtractor<List<?>> {

    @Override
    public void extractValues(List<?> originalValue, ValueReceiver receiver) {
        for ( int i = 0; i < originalValue.size(); i++ ) {
            receiver.indexedValue( "<list element>", i, originalValue.get( i ) );
        }
    }
}
```

--------------------------------

### Declaring Parameter Constraints

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates how to apply constraint annotations directly to method and constructor parameters to define preconditions for method invocation. These constraints ensure that method arguments meet specific criteria before the method's logic is executed.

```java
public class OrderService {

    public OrderService(@NotNull CreditCardProcessor creditCardProcessor) {
        [...]
    }

    public void placeOrder(
        @NotNull @Size(min=3, max=20) String customerCode,
        @NotNull Item item,
        @Min(1) int quantity) {
        [...]
    }
}
```

--------------------------------

### Accessing Provider-Specific APIs with unwrap

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates how to use the `unwrap` method to access provider-specific contracts, such as custom configurations for a particular implementation like ACME. This method allows for extending the standard Jakarta Validation API but makes the code non-portable.

```java
//if using the ACME provider
ACMEValidatorFactory acmeFactory = factory.unwrap(ACMEValidatorFactory.class);
acmeFactory.setSpecificConfiguration( [...] );
```

--------------------------------

### ConstraintValidator Implementations for Size

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Example implementations of ConstraintValidator for the @Size annotation, demonstrating specialization for different collection types like Collection, Set, and Serializable.

```java
public class SizeValidatorForCollection implements ConstraintValidator<Size, Collection> {
    [...]
}
```

```java
public class SizeValidatorForSet implements ConstraintValidator<Size, Set> {
    [...]
}
```

```java
public class SizeValidatorForSerializable implements ConstraintValidator<Size, Serializable> {
    [...]
}
```

--------------------------------

### Message Interpolation with Parameters

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Example of a message descriptor using parameters enclosed in curly braces. These parameters are typically resolved from resource bundles or constraint attributes.

```text
Value must be between {min} and {max}
```

--------------------------------

### Use Configuration to Build ValidatorFactory

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Instantiate a Configuration, customize it with a message interpolator and traversable resolver, and then build a ValidatorFactory. This is useful for setting up custom validation behavior.

```java
Configuration<?> configuration = [...];
ValidatorFactory factory = configuration
              .messageInterpolator( new WBMessageInterpolator() )
              .traversableResolver( new JPAAwareTraversableResolver() )
              .buildValidatorFactory();
```

--------------------------------

### Method Constraint Descriptors

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates retrieving and asserting properties of constraint descriptors for a method, including cross-parameter constraints.

```java
assert returnValueDescriptor.getConstraintDescriptors().size() == 2;
assert returnValueDescriptor.isCascaded() == false;

//void method which has a cross-parameter constraint
methodDescriptor = bookDescriptor.getConstraintsForMethod(
        "addChapter", String.class, int.class, int.class
);
assert methodDescriptor.getElementClass() == void.class;
assert methodDescriptor.hasConstrainedParameters() == true;
assert methodDescriptor.hasConstrainedReturnValue() == false;

//cross-parameter constraints accessible via separate descriptor
assert methodDescriptor.hasConstraints() == false;

assert methodDescriptor.getReturnValueDescriptor().getElementClass() == void.class;

//cross-parameter descriptor
CrossParameterDescriptor crossParameterDescriptor =
        methodDescriptor.getCrossParameterDescriptor();
assert crossParameterDescriptor.getElementClass() == Object[].class;
assert crossParameterDescriptor.hasConstraints() == true;

ConstraintDescriptor<?> crossParameterConstraint =
        crossParameterDescriptor.getConstraintDescriptors().iterator().next();
assert crossParameterConstraint.getAnnotation().annotationType() == ValidInterval.class;
```

--------------------------------

### Constructor Parameter Validation (Null Processor)

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Validates constructor parameters for the OrderService constructor. This example checks for a null CreditCardProcessor, expecting one constraint violation.

```java
executableValidator.validateConstructorParameters(constructor, new Object[] { null })
    .size() == 1;
```

--------------------------------

### Constructor-Level Constraint Mapping XML

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

This XML snippet demonstrates how to define constraints for a constructor, including its parameters, cross-parameter constraints, and return value. It shows how to specify parameter types, enable cascading validation with '<valid/>', and control annotation overriding.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<constraint-mappings
        xmlns="https://jakarta.ee/xml/ns/validation/mapping"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://jakarta.ee/xml/ns/validation/mapping
            https://jakarta.ee/xml/ns/validation/mapping/validation-mapping-3.0.xsd"
        version="3.0">
    <default-package>com.acme.app.domain</default-package>
    <bean class="Customer" ignore-annotations="false">
        <constructor ignore-annotations="true">
            <parameter type="java.lang.String">
                [...]
            </parameter>
            <parameter type="int">
                <valid/>
                [...]
            </parameter>
            <parameter type="long" ignore-annotations="false"/>
            <cross-parameter ignore-annotations="false">
                [...]
            </cross-parameter>
            <return-value>
                <valid/>
                [...]
            </return-value>
            [...]
        </constructor>

    </bean>
</constraint-mappings>
```

--------------------------------

### Configuration and BootstrapConfiguration Interfaces

Source: https://jakarta.ee/specifications/bean-validation/3.1/jakarta-validation-spec-3.1

Demonstrates the usage of the Configuration interface to customize a ValidatorFactory, including setting a custom message interpolator. The configuration information is typically retrieved from META-INF/validation.xml by default.

```java
/**
 * Receives configuration information, selects the appropriate
 * Jakarta Validation provider and builds the appropriate {@link ValidatorFactory}.
 * <p>
 * Usage:
 * <pre>
 * //provided by one of the Validation bootstrap methods
 * Configuration<?> configuration = ...;
 * ValidatorFactory = configuration
 *     .messageInterpolator( new CustomMessageInterpolator() )
 *     .buildValidatorFactory();
 * </pre>
 * <p>
 * By default, the configuration information is retrieved from
 * {@code META-INF/validation.xml}.
 */
```
Tokens:
Raw