javax.validation.Configuration Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of validation-api Show documentation
Bean Validation API
There is a newer version: 2.0.1.Final
/*
* Copyright 2009-2012, Red Hat, Inc. and/or its affiliates, and individual contributors
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package javax.validation;

import java.io.InputStream;

/**
 * Receives configuration information, selects the appropriate
 * Bean Validation provider and builds the appropriate {@code ValidatorFactory}.
 * 
 * Usage:
 * 
 * {@code
 * 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 {@code Configuration} methods.
 * 

 * The {@link ValidationProviderResolver} is specified at configuration time
 * (see {@link javax.validation.spi.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
 * {@code 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 {@code ValidationProviderResolver}
 * 
 * 
 * Implementations are not meant to be thread-safe.
 *
 * @author Emmanuel Bernard
 * @author Gunnar Morling
 * @author Hardy Ferentschik
 */
public interface Configuration> {

	/**
	 * Ignore 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 {@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 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 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);

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

	 * The stream should be closed by the client API after the
	 * {@code ValidatorFactory} has been built. The 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 Bean Validation provider.
	 *
	 * @return {@code this} following the chaining method pattern.
	 *
	 * @throws IllegalArgumentException
	 *             if {@code stream} is null
	 */
	T addMapping(InputStream stream);

	/**
	 * Add 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 {@code Configuration} subclass.
	 * 
{@code 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.
	 *
	 * @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);

	/**
	 * Return an implementation of the {@code MessageInterpolator} interface
	 * following the default {@code MessageInterpolator} defined in the
	 * specification:
	 * 

	 * use the ValidationMessages resource bundle to load keys
	 * use Locale.getDefault()
	 * 
	 *
	 * @return default MessageInterpolator implementation compliant with the specification
	 */
	MessageInterpolator getDefaultMessageInterpolator();

	/**
	 * Return an implementation of the {@code 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 TraversableResolver implementation compliant with the specification
	 */
	TraversableResolver getDefaultTraversableResolver();

	/**
	 * Return an implementation of the {@code ConstraintValidatorFactory} interface
	 * following the default {@code ConstraintValidatorFactory} defined in the
	 * specification:
	 * 
	 * uses the public no-arg constructor of the {@code ConstraintValidator}
	 * 
	 *
	 * @return default ConstraintValidatorFactory implementation compliant with the specification
	 */
	ConstraintValidatorFactory getDefaultConstraintValidatorFactory();

	/**
	 * Return an implementation of the {@code ParameterNameProvider}
	 * interface following the default {@code ParameterNameProvider}
	 * defined in the specification:
	 * 
	 * 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 ParameterNameProvider implementation compliant with
	 *         the specification
	 *
	 * @since 1.1
	 */
	ParameterNameProvider getDefaultParameterNameProvider();

	/**
	 * Return configuration information stored in the META-INF/validation.xml file.
	 * 
	 * Note:

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

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