Chapter 4. XML configuration

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. Example 4.1, “validation-configuration-1.0.xsd” shows a model view of the xsd valiation.xml has to adhere to.

Example 4.1. validation-configuration-1.0.xsd

Example 4.2, “validation.xml” shows the several configuration options of validation.xml.

Example 4.2. 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.engine.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>

Warning

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 Example 4.2, “validation.xml” 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 overriden by values explicitly specified via the API. It is even possible to ignore the XML configuration completely via Configuration.ignoreXmlConfiguration(). See also Chapter 5, Bootstrapping.

Via the constraint-mapping you can list an arbitrary number of additional XML files containing the actual constraint configuration. See Section 4.2, “Mapping constraints”.

Last but not least, you can specify provider specific properties via the property nodes. Hibernate Validator does currently not make use of any custom properties.

4.2. Mapping constraints

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

Example 4.3. validation-mapping-1.0.xsd

Example 4.4, “constraints-car.xml” shows how our classes Car and RentalCar from Example 2.15, “Car” resp. Example 2.19, “RentalCar” could be mapped in XML.

Example 4.4. 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.

Warning

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 Section 2.1, “Defining constraints”). 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 Section 2.3.2, “Redefining the default group sequence of a class”) 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.