javax.validation

## Interface Configuration<T extends Configuration<T>>

-     public interface Configuration<T extends Configuration<T>>

  Receives configuration information, selects the appropriate Bean Validation provider and builds the appropriate `ValidatorFactory`.

  Usage:

       Configuration configuration = //provided by one of the Validation bootstrap methods
           ValidatorFactory = configuration
               .messageInterpolator( new CustomMessageInterpolator() )
               .buildValidatorFactory();

  By default, the configuration information is retrieved from `META-INF/validation.xml`. It is possible to override the configuration retrieved from the XML file by using one or more of the `Configuration` methods.

  The `ValidationProviderResolver` is specified at configuration time (see `ValidationProvider`). If none is explicitly requested, the default `ValidationProviderResolver` is used.

  The provider is selected in the following way:
  - if a specific provider is requested programmatically using `Validation.byProvider(Class)`, find the first provider implementing the provider class requested and use it
  - if a specific provider is requested in `META-INF/validation.xml`>, find the first provider implementing the provider class requested and use it
  - otherwise, use the first provider returned by the `ValidationProviderResolver`

  Implementations are not meant to be thread-safe.
  Author:
    Emmanuel Bernard, Gunnar Morling, Hardy Ferentschik

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `T` | `addMapping(InputStream stream)` Add a stream describing constraint mapping in the Bean Validation XML format.
    `T` | `addProperty(String name, String value)` Adds a provider specific property.
    `ValidatorFactory` | `buildValidatorFactory()` Build a `ValidatorFactory` implementation.
    `T` | `constraintValidatorFactory(ConstraintValidatorFactory constraintValidatorFactory)` Defines the constraint validator factory.
    `BootstrapConfiguration` | `getBootstrapConfiguration()` Returns configuration information stored in the `META-INF/validation.xml` file.
    `ConstraintValidatorFactory` | `getDefaultConstraintValidatorFactory()` Returns an implementation of the `ConstraintValidatorFactory` interface following the default `ConstraintValidatorFactory` defined in the specification: uses the public no-arg constructor of the `ConstraintValidator`
    `MessageInterpolator` | `getDefaultMessageInterpolator()` Returns an implementation of the `MessageInterpolator` interface following the default `MessageInterpolator` defined in the specification: use the `ValidationMessages` resource bundle to load keys use `Locale.getDefault()`
    `ParameterNameProvider` | `getDefaultParameterNameProvider()` Returns an implementation of the `ParameterNameProvider` interface following the default `ParameterNameProvider` defined in the specification: returns names in the form `arg&lt;PARAMETER_INDEX&gt;` where `PARAMETER_INDEX` starts at 0 for the first parameter, e.g.
    `TraversableResolver` | `getDefaultTraversableResolver()` Returns an implementation of the `TraversableResolver` interface following the default `TraversableResolver` defined in the specification: if Java Persistence is available in the runtime environment, a property is considered reachable if Java Persistence considers the property as loaded if Java Persistence is not available in the runtime environment, all properties are considered reachable all properties are considered cascadable.
    `T` | `ignoreXmlConfiguration()` Ignores data from the `META-INF/validation.xml` file if this method is called.
    `T` | `messageInterpolator(MessageInterpolator interpolator)` Defines the message interpolator used.
    `T` | `parameterNameProvider(ParameterNameProvider parameterNameProvider)` Defines the parameter name provider.
    `T` | `traversableResolver(TraversableResolver resolver)` Defines the traversable resolver used.

- - ### Method Detail

    - #### ignoreXmlConfiguration

          T ignoreXmlConfiguration()

      Ignores data from the `META-INF/validation.xml` file if this method is called.

      This method is typically useful for containers that parse `META-INF/validation.xml` themselves and pass the information via the `Configuration` methods.
      Returns:
        `this` following the chaining method pattern.

    - #### messageInterpolator

          T messageInterpolator(MessageInterpolator interpolator)

      Defines the message interpolator used. Has priority over the configuration based message interpolator.

      If `null` is passed, the default message interpolator is used (defined in XML or the specification default).
      Parameters:
        `interpolator` - message interpolator implementation
      Returns:
        `this` following the chaining method pattern

    - #### traversableResolver

          T traversableResolver(TraversableResolver resolver)

      Defines the traversable resolver used. Has priority over the configuration based traversable resolver.

      If `null` is passed, the default traversable resolver is used (defined in XML or the specification default).
      Parameters:
        `resolver` - traversable resolver implementation
      Returns:
        `this` following the chaining method pattern

    - #### constraintValidatorFactory

          T constraintValidatorFactory(ConstraintValidatorFactory constraintValidatorFactory)

      Defines the constraint validator factory. Has priority over the configuration based constraint factory.

      If `null` is passed, the default constraint validator factory is used (defined in XML or the specification default).
      Parameters:
        `constraintValidatorFactory` - constraint factory implementation
      Returns:
        `this` following the chaining method pattern

    - #### parameterNameProvider

          T parameterNameProvider(ParameterNameProvider parameterNameProvider)

      Defines the parameter name provider. Has priority over the configuration based provider.

      If `null` is passed, the default parameter name provider is used (defined in XML or the specification default).
      Parameters:
        `parameterNameProvider` - parameter name provider implementation
      Returns:
        `this` following the chaining method pattern.
      Since:
        1.1

    - #### addMapping

          T addMapping(InputStream stream)

      Add a stream describing constraint mapping in the Bean Validation XML format.

      The stream should be closed by the client API after the `ValidatorFactory` has been built. The Bean Validation provider must not close the stream.
      Parameters:
        `stream` - XML mapping stream; the given stream should support the mark/reset contract (see `InputStream.markSupported()`); if it doesn't, it will be wrapped into a stream supporting the mark/reset contract by the Bean Validation provider
      Returns:
        `this` following the chaining method pattern
      Throws:
        `IllegalArgumentException` - if `stream` is null

    - #### addProperty

          T addProperty(String name,
                      String value)

      Adds a provider specific property. This property is equivalent to XML configuration properties. If the underlying provider does not know how to handle the property, it must silently ignore it.

      Note: Using this non type-safe method is generally not recommended.

      It is more appropriate to use, if available, the type-safe equivalent provided by a specific provider via its `Configuration` subclass.

           ValidatorFactory factory = Validation.byProvider(ACMEProvider.class)
               .configure()
                   .providerSpecificProperty(ACMEState.FAST)
               .buildValidatorFactory();

      This method is typically used by containers parsing `META-INF/validation.xml` themselves and injecting the state to the `Configuration` object.

      If a property with a given name is defined both via this method and in the XML configuration, the value set programmatically has priority.

      If `null` is passed as a value, the value defined in XML is used. If no value is defined in XML, the property is considered unset.
      Parameters:
        `name` - property name
        `value` - property value
      Returns:
        `this` following the chaining method pattern
      Throws:
        `IllegalArgumentException` - if `name` is null

    - #### getDefaultMessageInterpolator

          MessageInterpolator getDefaultMessageInterpolator()

      Returns an implementation of the `MessageInterpolator` interface following the default `MessageInterpolator` defined in the specification:
      - use the `ValidationMessages` resource bundle to load keys
      - use `Locale.getDefault()`
      Returns:
        default `MessageInterpolator` implementation compliant with the specification

    - #### getDefaultTraversableResolver

          TraversableResolver getDefaultTraversableResolver()

      Returns an implementation of the `TraversableResolver` interface following the default `TraversableResolver` defined in the specification:
      - if Java Persistence is available in the runtime environment, a property is considered reachable if Java Persistence considers the property as loaded
      - if Java Persistence is not available in the runtime environment, all properties are considered reachable
      - all properties are considered cascadable.
      Returns:
        default `TraversableResolver` implementation compliant with the specification

    - #### getDefaultConstraintValidatorFactory

          ConstraintValidatorFactory getDefaultConstraintValidatorFactory()

      Returns an implementation of the `ConstraintValidatorFactory` interface following the default `ConstraintValidatorFactory` defined in the specification:
      - uses the public no-arg constructor of the `ConstraintValidator`
      Returns:
        default `ConstraintValidatorFactory` implementation compliant with the specification

    - #### getDefaultParameterNameProvider

          ParameterNameProvider getDefaultParameterNameProvider()

      Returns an implementation of the `ParameterNameProvider` interface following the default `ParameterNameProvider` defined in the specification:
      - returns names in the form `arg&lt;PARAMETER_INDEX&gt;` where `PARAMETER_INDEX` starts at 0 for the first parameter, e.g. `arg0`, `arg1` etc.
      Returns:
        default `ParameterNameProvider` implementation compliant with the specification
      Since:
        1.1

    - #### getBootstrapConfiguration

          BootstrapConfiguration getBootstrapConfiguration()

      Returns configuration information stored in the `META-INF/validation.xml` file.

      Note:
      Implementations are encouraged to lazily build this object to delay parsing.
      Returns:
        returns an instance of `BootstrapConfiguration`; this method never returns `null`; if there is no `META-INF/validation.xml` the different getters of the returned instance will return `null` respectively an empty set or map
      Since:
        1.1

    - #### buildValidatorFactory

          ValidatorFactory buildValidatorFactory()

      Build a `ValidatorFactory` implementation.
      Returns:
        the `ValidatorFactory`
      Throws:
        `ValidationException` - if the `ValidatorFactory` cannot be built

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.