All Downloads are FREE. Search and download functionalities are using the official Maven repository.

jakarta.validation.Configuration Maven / Gradle / Ivy

There is a newer version: 4.0.0
Show newest version
/*
 * Jakarta Bean Validation API
 *
 * License: Apache License, Version 2.0
 * See the license.txt file in the root directory or .
 */
package jakarta.validation;

import java.io.InputStream;

import jakarta.validation.spi.ValidationProvider;
import jakarta.validation.valueextraction.ValueExtractor;
import jakarta.validation.valueextraction.ValueExtractorDeclarationException;

/**
 * Receives configuration information, selects the appropriate
 * Jakarta Bean Validation provider and builds the appropriate {@link ValidatorFactory}.
 * 

* Usage: *

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

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

* The {@link ValidationProviderResolver} is specified at configuration time * (see {@link ValidationProvider}). * If none is explicitly requested, the default {@code ValidationProviderResolver} is used. *

* The provider is selected in the following way: *

    *
  • if a specific provider is requested programmatically using * {@link Validation#byProvider(Class)}, find the first provider implementing * the provider class requested and use it
  • *
  • if a specific provider is requested in {@code META-INF/validation.xml}, * find the first provider implementing the provider class requested and use it
  • *
  • otherwise, use the first provider returned by the * {@code ValidationProviderResolver}
  • *
*

* Implementations are not meant to be thread-safe. * * @param the type of a provider-specific specialization of this contract * * @author Emmanuel Bernard * @author Gunnar Morling * @author Hardy Ferentschik * @author Guillaume Smet */ public interface Configuration> { /** * Ignores data from the {@code META-INF/validation.xml} file if this * method is called. *

* This method is typically useful for containers that parse * {@code META-INF/validation.xml} themselves and pass the information * via the {@code Configuration} methods. * * @return {@code this} following the chaining method pattern. */ T ignoreXmlConfiguration(); /** * Defines the message interpolator used. Has priority over the configuration * based message interpolator. *

* If {@code null} is passed, the default message interpolator is used * (defined in XML or the specification default). * * @param interpolator message interpolator implementation * @return {@code this} following the chaining method pattern */ T messageInterpolator(MessageInterpolator interpolator); /** * Defines the traversable resolver used. Has priority over the configuration * based traversable resolver. *

* If {@code null} is passed, the default traversable resolver is used * (defined in XML or the specification default). * * @param resolver traversable resolver implementation * @return {@code this} following the chaining method pattern */ T traversableResolver(TraversableResolver resolver); /** * Defines the constraint validator factory. Has priority over the configuration * based constraint factory. *

* If {@code null} is passed, the default constraint validator factory is used * (defined in XML or the specification default). * * @param constraintValidatorFactory constraint factory implementation * @return {@code this} following the chaining method pattern */ T constraintValidatorFactory(ConstraintValidatorFactory constraintValidatorFactory); /** * Defines the parameter name provider. Has priority over the configuration * based provider. *

* If {@code null} is passed, the default parameter name provider is used * (defined in XML or the specification default). * * @param parameterNameProvider parameter name provider implementation * @return {@code this} following the chaining method pattern. * * @since 1.1 */ T parameterNameProvider(ParameterNameProvider parameterNameProvider); /** * Defines the clock provider. Has priority over the configuration * based provider. *

* If {@code null} is passed, the default clock provider is used * (defined in XML or the specification default). * * @param clockProvider clock provider implementation * @return {@code this} following the chaining method pattern. * * @since 2.0 */ T clockProvider(ClockProvider clockProvider); /** * Adds a value extractor. Has priority over any extractor for the same * type and type parameter detected through the service loader or given in * the XML configuration. * * @param extractor value extractor implementation * @return {@code this} following the chaining method pattern. * @throws ValueExtractorDeclarationException if more than one extractor for * the same type and type parameter is added * @since 2.0 */ T addValueExtractor(ValueExtractor extractor); /** * Add a stream describing constraint mapping in the Jakarta Bean Validation XML * format. *

* The stream should be closed by the client API after the * {@link ValidatorFactory} has been built. The Jakarta Bean Validation provider * must not close the stream. * * @param stream * XML mapping stream; the given stream should support the * mark/reset contract (see {@link InputStream#markSupported()}); * if it doesn't, it will be wrapped into a stream supporting the * mark/reset contract by the Jakarta Bean Validation provider * * @return {@code this} following the chaining method pattern * @throws IllegalArgumentException if {@code stream} is null */ T addMapping(InputStream stream); /** * 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 {@link Configuration} subclass. *

	 * ValidatorFactory factory = Validation.byProvider(ACMEProvider.class)
	 *     .configure()
	 *         .providerSpecificProperty(ACMEState.FAST)
	 *     .buildValidatorFactory();
	 * 
* This method is typically used by containers parsing {@code META-INF/validation.xml} * themselves and injecting the state to the {@code 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 {@code 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. * * @param name property name * @param value property value * @return {@code this} following the chaining method pattern * @throws IllegalArgumentException if {@code name} is null */ T addProperty(String name, String value); /** * Returns an implementation of the {@link MessageInterpolator} interface * following the default {@code MessageInterpolator} defined in the * specification: *

    *
  • use the {@code ValidationMessages} resource bundle to load keys
  • *
  • use {@code Locale.getDefault()}
  • *
* * @return default {@code MessageInterpolator} implementation compliant with the * specification */ MessageInterpolator getDefaultMessageInterpolator(); /** * Returns an implementation of the {@link TraversableResolver} interface * following the default {@code 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.
  • *
* * @return default {@code TraversableResolver} implementation compliant with the * specification */ TraversableResolver getDefaultTraversableResolver(); /** * Returns an implementation of the {@link ConstraintValidatorFactory} interface * following the default {@code ConstraintValidatorFactory} defined in the * specification: *
    *
  • uses the public no-arg constructor of the {@link ConstraintValidator}
  • *
* * @return default {@code ConstraintValidatorFactory} implementation compliant with the * specification */ ConstraintValidatorFactory getDefaultConstraintValidatorFactory(); /** * Returns an implementation of the {@link ParameterNameProvider} * interface following the default {@code ParameterNameProvider} * defined in the specification: *
    *
  • returns the actual parameter names as provided in the validated * executable’s definition, if the class file of the executable contains * parameter name information
  • *
  • * otherwise returns names in the form {@code arg<PARAMETER_INDEX>}, * where {@code PARAMETER_INDEX} starts at 0 for the first parameter, * e.g. {@code arg0}, {@code arg1} etc.
  • *
* * @return default {@code ParameterNameProvider} implementation compliant with * the specification * * @since 1.1 */ ParameterNameProvider getDefaultParameterNameProvider(); /** * Returns an implementation of the {@link ClockProvider} * interface following the default {@code ClockProvider} * defined in the specification: *
    *
  • returns a clock representing the current system time and default time * zone.
  • *
* * @return default {@code ClockProvider} implementation compliant with * the specification * * @since 2.0 */ ClockProvider getDefaultClockProvider(); /** * Returns configuration information stored in the {@code META-INF/validation.xml} file. *

* Note: *
* 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(); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy