Example 4.12. Configuration interface

/**
 * Receives configuration information, selects the appropriate
 * Bean Validation provider and build the appropriate
 * 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
 * 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 {@link javax.validation.spi.ValidationProvider}).
 * If none is explicitely requested, the default ValidationProviderResolver is used.
 * <p/>
 * The provider is selected in the following way:
 * - if a specific Configuration subclass is requested programmatically using
 * Validation.byProvider(Class), find the first provider matching it
 * - if a specific Configuration subclass is defined in META-INF/validation.xml,
 * find the first provider matching it
 * - otherwise, use the first provider returned by the ValidationProviderResolver
 * <p/>
 * Implementations are not meant to be thread-safe
 *
 * @author Emmanuel Bernard
 */
public interface Configuration<T extends Configuration<T>> {

    /**
     * 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 Configuration methods.
     */
    T ignoreXmlConfiguration();
    /**
     * Defines the message interpolator used. Has priority over the configuration
     * based message interpolator.
     *
     * @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.
     *
     * @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.
     *
     * @param constraintValidatorFactory constraint factory inmplementation.
     *
     * @return <code>this</code> following the chaining method pattern.
     */
    T constraintValidatorFactory(ConstraintValidatorFactory constraintValidatorFactory);

    /**
     * Add a stream describing constaint mapping in the Bean Validation
     * XML format.
     * <p/>
     * The stream should be closed by the client API after the
     * ValidatorFactory 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.
     */
    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 in its Configuration subclass.
     * <code>ValidatorFactory factory = Validation.byProvider(ACMEConfiguration.class)
     *        .configure()
     *           .providerSpecificProperty(ACMEState.FAST)
     *           .buildValidatorFactory();
     * </code>
     * 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.
     */
    T addProperty(String name, String value);

    /**
     * Return 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()
     *
     * @return default MessageInterpolator implementation compliant with the specification
     */
    MessageInterpolator getDefaultMessageInterpolator();

    /**
     * Build a ValidatorFactory implementation.
     *
     * @return ValidatorFactory
     */
    ValidatorFactory buildValidatorFactory();
}

Example 4.13. Example of provider specific Configuration sub interface

/**
 * Unique identifier of the ACME provider
 * also host some provider specific configuration methods
 */
public interface ACMEConfiguration 
    extends Configuration<ACMEonfiguration> {

    /**
     * Enables contraints implementation dynamic reloading when using ACME
     * default to false
     */
    Configuration enableDynamicReloading(boolean);

}

Example 4.14. ConfigurationState interface

/**
 * Contract between a <code>Configuration</code> and a
 * </code>ValidatorProvider</code> to create a <code>ValidatorFactory</code>.
 * The configuration artifacts defined in the XML configuration and provided to the
 * <code>Configuration</code> are merged and passed along via ConfigurationState.
 *
 * @author Emmanuel Bernard
 * @author Hardy Ferentschik
 */
public interface ConfigurationState {

    /**
     * returns true if Configuration.ignoreXMLConfiguration() has been called
     * In this case, the ValiatorFactory must ignore META-INF/validation.xml
     * @return true if META-INF/validation.xml should be ignored
     */
    boolean isIgnoreXmlConfiguration();

    /**
     * Message interpolator as defined in the following decresing priority:
     *  - set via the Configuration programmatic API
     *  - defined in META-INF/validation.xml provided that ignoredXmlConfiguration
     * is false. In this case the instance is created via its no-arg constructor.
     *  - null if undefined.
     *
     * @return message provider instance or null if not defined
     */
    MessageInterpolator getMessageInterpolator();

    /**
     * Returns a set of stream corresponding to:
     *  - mapping XML streams passed programmatically in Configuration
     *  - mapping XML stream located in the resources defined in
     * META-INF/validation.xml (constraint-mapping element)
     *
     * Streams represented in the XML configuration and opened by the 
     * configuration implementation must be closed by the configuration
     * implementation after the ValidatorFactory creation (or if an exception
     * occurs).
     *
     * @return set of input stream
     */
    Set<InputStream> getMappingStreams();

    /**
     * ConstraintValidatorFactory implementation as defined in the following
     * decreasing priority:
     *  - set via the Configuration programmatic API
     *  - defined in META-INF/validation.xml provided that ignoredXmlConfiguration
     * is false. In this case the instance is created via its no-arg constructor.
     *  - null if undefined.
     *
     * @return factory instance or null if not defined
     */
    ConstraintValidatorFactory getConstraintValidatorFactory();

    /**
     * TraversableResolver as defined in the following decresing priority:
     *  - set via the Configuration programmatic API
     *  - defined in META-INF/validation.xml provided that ignoredXmlConfiguration
     * is false. In this case the instance is created via its no-arg constructor.
     *  - null if undefined.
     *
     * @return traversable provider instance or null if not defined
     */
    TraversableResolver getTraversableResolver();

    /**
     * return  non type-safe properties defined via:
     *  - Configuration.addProperty(String, String)
     *  - META-INF/validation.xml provided that ignoredXmlConfiguration
     * is false.
     *
     * If a property is defined both programmatically and in XML,
     * the value defined programmatically has priority 
     *
     * @return Map whose key is the property key and the value the property value
     */
    Map<String, String> getProperties();
}

Example 4.15. Use Configuration

Configuration configuration = ...
ValidatorFactory factory = configuration
              .messageInterpolator( new WBMessageInterpolator() )
              .traversableResolver( new JPAAwareTraversableResolver() )
              .buildValidatorFactory();