# XML configuration

## `validation.xml`

The key to enable XML configuration for Hibernate Validator is the file `validation.xml`. If this file exists in the classpath its configuration will be applied when the ValidationFactory gets created. shows a model view of the xsd `valiation.xml` has to adhere to.

validation-configuration-1.0.xsd

shows the several configuration options of `validation.xml`.

validation.xml

    <validation-config xmlns="http://jboss.org/xml/ns/javax/validation/configuration"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/configuration">
        <default-provider>org.hibernate.validator.HibernateValidator</default-provider>
        <message-interpolator>org.hibernate.validator.messageinterpolation.ResourceBundleMessageInterpolator</message-interpolator>
        <traversable-resolver>org.hibernate.validator.engine.resolver.DefaultTraversableResolver</traversable-resolver>
        <constraint-validator-factory>org.hibernate.validator.engine.ConstraintValidatorFactoryImpl</constraint-validator-factory>
        <constraint-mapping>/constraints-car.xml</constraint-mapping>
        <property name="prop1">value1</property>
        <property name="prop2">value2</property>
    </validation-config>

There can only be one `validation.xml` in the classpath. If more than one is found an exception is thrown.

All settings shown in the `validation.xml` are optional and in the case of show the defaults used within Hibernate Validator. The node default-provider allows to choose the Bean Validation provider. This is useful if there is more than one provider in the classpath. message-interpolator, traversable-resolver and constraint-validator-factory allow to customize the javax.validation.MessageInterpolator, javax.validation.TraversableResolver resp. javax.validation.ConstraintValidatorFactory. The same configuration options are also available programmatically through the javax.validation.Configuration. In fact XML configuration will be overridden by values explicitly specified via the API. It is even possible to ignore the XML configuration completely via Configuration.ignoreXmlConfiguration(). See also .

Via the constraint-mapping you can list an arbitrary number of additional XML files containing the actual constraint configuration. See .

Last but not least, you can specify provider specific properties via the property nodes.

## Mapping constraints

Expressing constraints in XML is possible via files adhering to the xsd seen in . Note that these mapping files are only processed if listed via constraint-mapping in your `validation.xml`.

validation-mapping-1.0.xsd

shows how our classes Car and RentalCar from resp. could be mapped in XML.

constraints-car.xml

    <constraint-mappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                         xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/mapping validation-mapping-1.0.xsd"
                         xmlns="http://jboss.org/xml/ns/javax/validation/mapping">
        <default-package>org.hibernate.validator.quickstart</default-package>
        <bean class="Car" ignore-annotations="true">
            <field name="manufacturer">
                <constraint annotation="javax.validation.constraints.NotNull"/>
            </field>
            <field name="licensePlate">
                <constraint annotation="javax.validation.constraints.NotNull"/>
            </field>
            <field name="seatCount">
                <constraint annotation="javax.validation.constraints.Min">
                    <element name="value">2</element>
                </constraint>
            </field>
            <field name="driver">
                <valid/>
            </field>
            <getter name="passedVehicleInspection" ignore-annotations="true">
                <constraint annotation="javax.validation.constraints.AssertTrue">
                    <message>The car has to pass the vehicle inspection first</message>
                    <groups>
                        <value>CarChecks</value>
                    </groups>
                    <element name="max">10</element>
                </constraint>
            </getter>
        </bean>
        <bean class="RentalCar" ignore-annotations="true">
            <class ignore-annotations="true">
                <group-sequence>
                    <value>RentalCar</value>
                    <value>CarChecks</value>
                </group-sequence>
            </class>
        </bean>
        <constraint-definition annotation="org.mycompany.CheckCase" include-existing-validator="false">
            <validated-by include-existing-validators="false">
                <value>org.mycompany.CheckCaseValidator</value>
            </validated-by>
        </constraint-definition>
    </constraint-mappings>

The XML configuration is closely mirroring the programmatic API. For this reason it should suffice to just add some comments. default-package is used for all fields where a classname is expected. If the specified class is not fully qualified the configured default package will be used. Every mapping file can then have several bean nodes, each describing the constraints on the entity with the specified class name.

A given entity can only be configured once across all configuration files. If the same class is configured more than once an exception is thrown.

Settings ignore-annotations to true means that constraint annotations placed on the configured bean are ignored. The default for this value is `true`. ignore-annotations is also available for the nodes class, fields and getter. If not explicitly specified on these levels the configured bean value applies. Otherwise do the nodes class, fields and getter determine on which level the constraints are placed (see ). The constraint node is then used to add a constraint on the corresponding level. Each constraint definition must define the class via the annotation attribute. The constraint attributes required by the Bean Validation specification (message, groups and payload) have dedicated nodes. All other constraint specific attributes are configured using the the element node.

The class node also allows to reconfigure the default group sequence (see ) via the group-sequence node.

Last but not least, the list of ConstraintValidators associated to a given constraint can be altered via the constraint-definition node. The annotation attribute represents the constraint annotation being altered. The validated-by elements represent the (ordered) list of ConstraintValidator implementations associated to the constraint. If include-existing-validator is set to `false`, validators defined on the constraint annotation are ignored. If set to `true`, the list of ConstraintValidators described in XML are concatenated to the list of validators described on the annotation.