<?xml version="1.0" encoding="UTF-8"?>
<!--
	~ 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.
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../hv.ent">
%BOOK_ENTITIES;
]>
<chapter id="validator-xmlconfiguration">
  <title>XML configuration</title>

  <section>
    <title><filename>validation.xml</filename></title>

    <para>The key to enable XML configuration for Hibernate Validator is the
    file <filename>validation.xml</filename>. If this file exists in the
    classpath its configuration will be applied when the
    <classname>ValidationFactory</classname> gets created. <xref
    linkend="image-validation-configuration" /> shows a model view of the xsd
    <filename>valiation.xml</filename> has to adhere to.<example
        id="image-validation-configuration">
        <title>validation-configuration-1.0.xsd</title>

        <mediaobject>
          <imageobject role="fo">
            <imagedata align="center"
                       fileref="validation-configuration-1.0.png" scalefit="1" />
          </imageobject>

          <imageobject role="html">
            <imagedata depth="" fileref="validation-configuration-1.0.png"
                       scalefit="1" />
          </imageobject>
        </mediaobject>
      </example></para>

    <para><xref linkend="example-validation-xml" /> shows the several
    configuration options of <filename>validation.xml</filename>.</para>

    <example id="example-validation-xml">
      <title>validation.xml</title>

      <programlisting language="XML" role="XML">&lt;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"&gt;
    &lt;default-provider&gt;org.hibernate.validator.HibernateValidator&lt;/default-provider&gt;
    &lt;message-interpolator&gt;org.hibernate.validator.messageinterpolation.ResourceBundleMessageInterpolator&lt;/message-interpolator&gt;
    &lt;traversable-resolver&gt;org.hibernate.validator.engine.resolver.DefaultTraversableResolver&lt;/traversable-resolver&gt;
    &lt;constraint-validator-factory&gt;org.hibernate.validator.engine.ConstraintValidatorFactoryImpl&lt;/constraint-validator-factory&gt;
    &lt;constraint-mapping&gt;/constraints-car.xml&lt;/constraint-mapping&gt;
    &lt;property name="prop1"&gt;value1&lt;/property&gt;
    &lt;property name="prop2"&gt;value2&lt;/property&gt;
&lt;/validation-config&gt;</programlisting>
    </example>

    <warning>
      <para>There can only be one <filename>validation.xml</filename> in the
      classpath. If more than one is found an exception is thrown.</para>
    </warning>

    <para>All settings shown in the <filename>validation.xml</filename> are
    optional and in the case of <xref linkend="example-validation-xml" /> show
    the defaults used within Hibernate Validator. The node
    <property>default-provider</property> allows to choose the Bean Validation
    provider. This is useful if there is more than one provider in the
    classpath. <property>message-interpolator</property>,
    <property>traversable-resolver</property> and
    <property>constraint-validator-factory</property> allow to customize the
    <classname>javax.validation.MessageInterpolator</classname>,
    <classname>javax.validation.TraversableResolver</classname> resp.
    <classname>javax.validation.ConstraintValidatorFactory</classname>. The
    same configuration options are also available programmatically through the
    <classname>javax.validation.Configuration</classname>. 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
    <methodname> Configuration.ignoreXmlConfiguration()</methodname>. See also
    <xref linkend="validator-bootstrapping" />.</para>

    <para>Via the <property>constraint-mapping</property> you can list an
    arbitrary number of additional XML files containing the actual constraint
    configuration. See <xref linkend="section-mapping-constraints" />.</para>

    <para>Last but not least, you can specify provider specific properties via
    the <property>property</property> nodes.</para>
  </section>

  <section>
    <title id="section-mapping-constraints">Mapping constraints</title>

    <para>Expressing constraints in XML is possible via files adhering to the
    xsd seen in <xref linkend="image-mapping-configuration" />. Note that
    these mapping files are only processed if listed via
    <property>constraint-mapping</property> in your
    <filename>validation.xml</filename>.</para>

    <example id="image-mapping-configuration">
      <title>validation-mapping-1.0.xsd</title>

      <mediaobject>
        <imageobject role="fo">
          <imagedata align="center" contentdepth="240mm"
                     fileref="validation-mapping-1.0.png" scalefit="" />
        </imageobject>

        <imageobject role="html">
          <imagedata depth="" fileref="validation-mapping-1.0.png"
                     scalefit="1" />
        </imageobject>
      </mediaobject>
    </example>

    <para><xref linkend="example-constraints-car" /> shows how our classes Car
    and RentalCar from <xref linkend="example-car" /> resp. <xref
    linkend="example-rental-car" /> could be mapped in XML.</para>

    <example id="example-constraints-car">
      <title>constraints-car.xml</title>

      <programlisting language="XML" role="XML">&lt;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"&gt;
    &lt;default-package&gt;org.hibernate.validator.quickstart&lt;/default-package&gt;
    &lt;bean class="Car" ignore-annotations="true"&gt;
        &lt;field name="manufacturer"&gt;
            &lt;constraint annotation="javax.validation.constraints.NotNull"/&gt;
        &lt;/field&gt;
        &lt;field name="licensePlate"&gt;
            &lt;constraint annotation="javax.validation.constraints.NotNull"/&gt;
        &lt;/field&gt;
        &lt;field name="seatCount"&gt;
            &lt;constraint annotation="javax.validation.constraints.Min"&gt;
                &lt;element name="value"&gt;2&lt;/element&gt;
            &lt;/constraint&gt;
        &lt;/field&gt;
        &lt;field name="driver"&gt;
            &lt;valid/&gt;
        &lt;/field&gt;
        &lt;getter name="passedVehicleInspection" ignore-annotations="true"&gt;
            &lt;constraint annotation="javax.validation.constraints.AssertTrue"&gt;
                &lt;message&gt;The car has to pass the vehicle inspection first&lt;/message&gt;
                &lt;groups&gt;
                    &lt;value&gt;CarChecks&lt;/value&gt;
                &lt;/groups&gt;
                &lt;element name="max"&gt;10&lt;/element&gt;
            &lt;/constraint&gt;
        &lt;/getter&gt;
    &lt;/bean&gt;
    &lt;bean class="RentalCar" ignore-annotations="true"&gt;
        &lt;class ignore-annotations="true"&gt;
            &lt;group-sequence&gt;
                &lt;value&gt;RentalCar&lt;/value&gt;
                &lt;value&gt;CarChecks&lt;/value&gt;
            &lt;/group-sequence&gt;
        &lt;/class&gt;
    &lt;/bean&gt;
    &lt;constraint-definition annotation="org.mycompany.CheckCase"&gt;
        &lt;validated-by include-existing-validators="false"&gt;
            &lt;value&gt;org.mycompany.CheckCaseValidator&lt;/value&gt;
        &lt;/validated-by&gt;
    &lt;/constraint-definition&gt;
&lt;/constraint-mappings&gt;</programlisting>
    </example>

    <para>The XML configuration is closely mirroring the programmatic API. For
    this reason it should suffice to just add some comments.
    <property>default-package</property> 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 <property>bean</property> nodes, each describing the constraints
    on the entity with the specified class name.<warning>
        <para>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.</para>
      </warning>Settings <property>ignore-annotations</property> to true means
    that constraint annotations placed on the configured bean are ignored. The
    default for this value is <constant>true</constant>. ignore-annotations is
    also available for the nodes <property>class</property>,
    <property>fields</property> and <property>getter</property>. If not
    explicitly specified on these levels the configured
    <property>bean</property> value applies. Otherwise do the nodes
    <property>class</property>, <property>fields</property> and
    <property>getter</property> determine on which level the constraints are
    placed (see <xref linkend="validator-usingvalidator-annotate" />). The
    <property>constraint</property> 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 (<property>message</property>,
    <property>groups</property> and <property>payload</property>) have
    dedicated nodes. All other constraint specific attributes are configured
    using the the <property>element</property> node.</para>

    <para>The class node also allows to reconfigure the default group sequence
    (see <xref linkend="section-default-group-class" />) via the
    <property>group-sequence</property> node.</para>

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