| // $Id: Configuration.java 17620 2009-10-04 19:19:28Z hardy.ferentschik $ |
| /* |
| * JBoss, Home of Professional Open Source |
| * Copyright 2009, 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. |
| */ |
| // Changed by Google |
| package javax.validation; |
| |
| |
| /** |
| * Receives configuration information, selects the appropriate |
| * Bean Validation provider and builds the appropriate <code>ValidatorFactory</code>. |
| * <p/> |
| * Usage: |
| * <pre> |
| * {@code |
| * 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 |
| * <i>META-INF/validation.xml</i>. |
| * It is possible to override the configuration retrieved from the XML file |
| * by using one or more of the <code>Configuration</code> methods. |
| * <p/> |
| * The {@link ValidationProviderResolver} is specified at configuration time |
| * (see {@link javax.validation.spi.ValidationProvider}). |
| * If none is explicitly requested, the default <code>ValidationProviderResolver</code> is used. |
| * <p/> |
| * The provider is selected in the following way: |
| * <ul> |
| * <li>if a specific provider is requested programmatically using |
| * <code>Validation.byProvider(Class)</code>, find the first provider implementing |
| * the provider class requested and use it</li> |
| * <li>if a specific provider is requested in <i>META-INF/validation.xml</i>, |
| * find the first provider implementing the provider class requested and use it</li> |
| * <li>otherwise, use the first provider returned by the <code>ValidationProviderResolver<code></li> |
| * </ul> |
| * <p/> |
| * Implementations are not meant to be thread-safe. |
| * |
| * @author Emmanuel Bernard |
| */ |
| public interface Configuration<T extends Configuration<T>> { |
| |
| /** |
| * Ignore data from the <i>META-INF/validation.xml</i> file if this |
| * method is called. |
| * This method is typically useful for containers that parse |
| * <i>META-INF/validation.xml</i> themselves and pass the information |
| * via the <code>Configuration</code> methods. |
| * |
| * @return <code>this</code> following the chaining method pattern. |
| */ |
| T ignoreXmlConfiguration(); |
| |
| /** |
| * Defines the message interpolator used. Has priority over the configuration |
| * based message interpolator. |
| * If <code>null</code> is passed, the default message interpolator is used |
| * (defined in XML or the specification default). |
| * |
| * @param interpolator message interpolator implementation. |
| * |
| * @return <code>this</code> 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</code> is passed, the default traversable resolver is used |
| * (defined in XML or the specification default). |
| * |
| * @param resolver traversable resolver implementation. |
| * |
| * @return <code>this</code> 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 inmplementation. |
| * |
| * @return <code>this</code> following the chaining method pattern. |
| */ |
| T constraintValidatorFactory(ConstraintValidatorFactory constraintValidatorFactory); |
| |
| /** |
| * Add a stream describing constraint mapping in the Bean Validation |
| * XML format. |
| * <p/> |
| * The stream should be closed by the client API after the |
| * <code>ValidatorFactory</code> has been built. The Bean Validation provider |
| * must not close the stream. |
| * |
| * @param stream XML mapping stream. |
| * |
| * @return <code>this</code> following the chaining method pattern. |
| * @throws IllegalArgumentException if <code>stream</code> is null |
| */ |
| T addMapping(String 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. |
| * <p/> |
| * Note: Using this non type-safe method is generally not recommended. |
| * <p/> |
| * It is more appropriate to use, if available, the type-safe equivalent provided |
| * by a specific provider via its <code>Configuration<code> subclass. |
| * <code>ValidatorFactory factory = Validation.byProvider(ACMEPrivoder.class) |
| * .configure() |
| * .providerSpecificProperty(ACMEState.FAST) |
| * .buildValidatorFactory(); |
| * </code> |
| * This method is typically used by containers parsing <i>META-INF/validation.xml</i> |
| * themselves and injecting the state to the Configuration object. |
| * <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. |
| * |
| * 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</code> following the chaining method pattern. |
| * |
| * @throws IllegalArgumentException if <code>name</code> is null |
| */ |
| T addProperty(String name, String value); |
| |
| /** |
| * Return an implementation of the <code>MessageInterpolator</code> interface |
| * following the default <code>MessageInterpolator</code> defined in the |
| * specification: |
| * <ul> |
| * <li>use the ValidationMessages resource bundle to load keys</li> |
| * <li>use Locale.getDefault()</li> |
| * </ul> |
| * |
| * @return default MessageInterpolator implementation compliant with the specification |
| */ |
| MessageInterpolator getDefaultMessageInterpolator(); |
| |
| /** |
| * Return an implementation of the <code>TraversableResolver</code> interface |
| * following the default <code>TraversableResolver</code> 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 TraversableResolver implementation compliant with the specification |
| */ |
| TraversableResolver getDefaultTraversableResolver(); |
| |
| /** |
| * Return an implementation of the <code>ConstraintValidatorFactory</code> interface |
| * following the default <code>ConstraintValidatorFactory</code> defined in the |
| * specification: |
| * <ul> |
| * <li>uses the public no-arg constructor of the <code>ConstraintValidator</code></li> |
| * </ul> |
| * |
| * @return default ConstraintValidatorFactory implementation compliant with the specification |
| */ |
| ConstraintValidatorFactory getDefaultConstraintValidatorFactory(); |
| |
| /** |
| * Build a <code>ValidatorFactory</code> implementation. |
| * |
| * @return ValidatorFactory |
| * @throws ValidationException if the ValidatorFactory cannot be built |
| */ |
| ValidatorFactory buildValidatorFactory(); |
| } |