/*
* 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;
import javax.validation.spi.ValidationProvider;
// TODO: this interface is unchanged, remove it, when super implementation is removed from gwt
/**
* Receives configuration information, selects the appropriate Bean Validation provider and builds
* the appropriate {@link ValidatorFactory}.
* <p/>
* Usage:
*
* <pre>
* Configuration<?> configuration = // provided by one of the Validation bootstrap methods
* ValidatorFactory = configuration.messageInterpolator(new CustomMessageInterpolator())
* .buildValidatorFactory();
* </pre>
* <p/>
* 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.
* <p/>
* The {@link ValidationProviderResolver} is specified at configuration time (see
* {@link ValidationProvider}). If none is explicitly requested, the default
* {@code ValidationProviderResolver} is used.
* <p/>
* The provider is selected in the following way:
* <ul>
* <li>if a specific provider is requested programmatically using
* {@link Validation#byProvider(Class)}, find the first provider implementing the provider class
* requested and use it</li>
* <li>if a specific provider is requested in {@code META-INF/validation.xml}>, find the first
* provider implementing the provider class requested and use it</li>
* <li>otherwise, use the first provider returned by the {@code ValidationProviderResolver}</li>
* </ul>
* <p/>
* Implementations are not meant to be thread-safe.
*
* @author Emmanuel Bernard
* @author Gunnar Morling
* @author Hardy Ferentschik
*/
public interface Configuration<T extends Configuration<T>> {
/**
* Ignores data from the {@code META-INF/validation.xml} file if this method is called.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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);
/**
* Add a stream describing constraint mapping in the Bean Validation XML format.
* <p/>
* The stream should be closed by the client API after the {@link 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);
/**
* 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.
*
* <p>
* Note: Using this non type-safe method is generally not recommended.
* </p>
*
* <p>
* It is more appropriate to use, if available, the type-safe equivalent provided by a specific
* provider via its {@link Configuration} subclass.
*
* <pre>
* ValidatorFactory factory = Validation.byProvider(ACMEProvider.class).configure()
* .providerSpecificProperty(ACMEState.FAST).buildValidatorFactory();
* </pre>
* </p>
*
* <p>
* This method is typically used by containers parsing {@code META-INF/validation.xml} themselves
* and injecting the state to the {@code Configuration} object.
* </p>
*
* <p>
* If a property with a given name is defined both via this method and in the XML configuration,
* the value set programmatically has priority.
* </p>
*
* <p>
* 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.
* </p>
*
* @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:
* <ul>
* <li>use the {@code ValidationMessages} resource bundle to load keys</li>
* <li>use {@code Locale.getDefault()}</li>
* </ul>
*
* @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:
* <ul>
* <li>if Java Persistence is available in the runtime environment, a property is considered
* reachable if Java Persistence considers the property as loaded</li>
* <li>if Java Persistence is not available in the runtime environment, all properties are
* considered reachable</li>
* <li>all properties are considered cascadable.</li>
* </ul>
*
* @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.
* <ul>
* <li>uses the public no-arg constructor of the {@link ConstraintValidator}</li>
* </ul>
*
* @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:
* <ul>
* <li>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.</li>
* </ul>
*
* @return default {@code ParameterNameProvider} implementation compliant with the specification
*
* @since 1.1
*/
ParameterNameProvider getDefaultParameterNameProvider();
/**
* 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();
}