/
xmlconfiguration.xml
294 lines (261 loc) · 14.2 KB
/
xmlconfiguration.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
<?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>Configuring via XML</title>
<para>So far we have used the default configuration source for Bean
Validation, namely annotations. However, there also exist two kinds of XML
descriptors allowing configuration via XML. The first descriptor describes
general Bean Validation behaviour and is provided as
<filename>META-INF/validation.xml</filename>. The second one describes
constraint declarations and closely matches the constraint declaration
approach via annotations. Let's have a look at these two document
types.<note>
<para>There are actually two versions for each descriptor type, one for
Bean Validation 1.0 and one for Bean Validation 1.1. Both versions are
supported, but we recommend the use of the latter together with
Hibernate Validator 5.x. The xsd files are available via <ulink
url="http://www.jboss.org/xml/ns/javax/validation/configuration/">http://www.jboss.org/xml/ns/javax/validation/configuration</ulink>
and <ulink
url="http://www.jboss.org/xml/ns/javax/validation/mapping">http://www.jboss.org/xml/ns/javax/validation/mapping</ulink>.</para>
</note></para>
<section>
<title>Configuring ValidationFactory in
<filename>validation.xml</filename></title>
<para>The key to enable XML configuration for Hibernate Validator is the
file <filename>META-INF/validation.xml</filename>. If this file exists on
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 XML
schema to which <filename>validation.xml</filename> has to adhere.<example
id="image-validation-configuration">
<title>validation-configuration-1.1.xsd</title>
<mediaobject>
<imageobject role="fo">
<imagedata align="center"
fileref="validation-configuration-1.1.png" format="PNG"
width="80%"/>
</imageobject>
<imageobject role="html">
<imagedata depth="" fileref="validation-configuration-1.1.png"
format="PNG" scalefit="1"/>
</imageobject>
</mediaobject>
</example></para>
<para><xref linkend="example-validation-xml"/> shows the several
configuration options of <filename>validation.xml</filename> using the
Hibernate Validator built-in defaults. All settings are optional and the
same configuration options are also available programmatically through
<classname>javax.validation.Configuration</classname>. In fact the XML
configuration will be overridden by values explicitly specified via the
programmatic API. It is even possible to ignore the XML configuration
completely via
<methodname>Configuration.ignoreXmlConfiguration()</methodname>. See also
<xref linkend="validator-bootstrapping"/>.</para>
<example id="example-validation-xml">
<title>validation.xml with Hibernate Validator defaults</title>
<programlisting language="XML" role="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.internal.engine.resolver.DefaultTraversableResolver
</traversable-resolver>
<constraint-validator-factory>
org.hibernate.validator.internal.engine.constraintvalidation.ConstraintValidatorFactoryImpl
</constraint-validator-factory>
<parameter-name-provider>
org.hibernate.validator.internal.engine.DefaultParameterNameProvider
</parameter-name-provider>
<executable-validation enabled="true">
<default-validated-executable-types>
<executable-type>CONSTRUCTORS</executable-type>
<executable-type>NON_GETTER_METHODS</executable-type>
</default-validated-executable-types>
</executable-validation>
<constraint-mapping>META-INF/validation/constraints-car.xml</constraint-mapping>
<property name="hibernate.validator.fail_fast">false</property>
</validation-config></programlisting>
</example>
<warning>
<para>There must only be one file named
<filename>META-INF/validation.xml</filename> on the classpath. If more
than one is found an exception is thrown.</para>
</warning>
<para>The node <property>default-provider</property> allows to choose the
Bean Validation provider. This is useful if there is more than one
provider on the classpath. <property>message-interpolator</property>,
<property>traversable-resolver</property>,
<property>constraint-validator-factory</property> and
<property>parameter-name-provider</property> allow to customize the used
implementations for the interfaces
<classname>MessageInterpolator</classname>,
<classname>TraversableResolver</classname>,
<classname>ConstraintValidatorFactory</classname> and
<classname>ParameterNameProvider</classname> defined in the
<classname>javax.validation</classname> package. See <xref
linkend="validator-bootstrapping"/> for more information about these
interfaces.</para>
<para><property>executable-validation</property> and its subnodes define
defaults for method validation. The Bean Validation specification defines
constructor and non getter methods as defaults. The
<property>enabled</property> attribute acts as global switch to turn
method validation on and off (see also TODO - reference to method
validation).</para>
<para>Via the <property>constraint-mapping</property> element you can list
an arbitrary number of additional XML files containing the actual
constraint configuration. Mapping file names must be specified using their
fully-qualified name on the classpath. Details on writing mapping files
can be found in the next section.</para>
<para>Last but not least, you can specify provider specific properties via
the <property>property</property> nodes. In the example we are using the
Hibernate Validator specific
<property>hibernate.validator.fail_fast</property> property (see <xref
linkend="failfast"/>).</para>
</section>
<section>
<title id="section-mapping-constraints">Mapping constraints via
<property>constraint-mappings</property></title>
<para>Expressing constraints in XML is possible via files adhering to the
schema seen in <xref linkend="image-mapping-configuration"/>. Note that
these mapping files are only processed if listed via
<property>constraint-mapping</property> in
<filename>validation.xml</filename>.</para>
<example id="image-mapping-configuration">
<title>validation-mapping-1.1.xsd</title>
<mediaobject>
<imageobject role="fo">
<imagedata align="center" contentdepth="200mm"
fileref="validation-mapping-1.1.png" format="PNG"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="validation-mapping-1.1.png" format="PNG"
scalefit="1"/>
</imageobject>
</mediaobject>
</example>
<para><xref linkend="example-constraints-car"/> shows how our classes
<classname>Car</classname> and <classname>RentalCar</classname> from <xref
linkend="example-car"/> resp. <xref linkend="example-rental-car"/> could
be mapped in XML. Example x shows how method validation from example y can
be expressed in xml. (TODO create example)</para>
<example id="example-constraints-car">
<title>constraints.xml</title>
<programlisting language="XML" role="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.1.xsd"
xmlns="http://jboss.org/xml/ns/javax/validation/mapping" version="1.1">
<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">
<validated-by include-existing-validators="false">
<value>org.mycompany.CheckCaseValidator</value>
</validated-by>
</constraint-definition>
</constraint-mappings></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 class
name 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. The same applies for constraint defintions for a
given constraint annotation. It can only occur in one mapping file. If
these rules are violated a <classname>ValidationException</classname>
is thrown.</para>
</warning>Setting <property>ignore-annotations</property> to
<constant>true</constant> 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 <property>annotation</property> 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 <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
constraint validators described in XML is concatenated to the list of
validators specified on the annotation.</para>
</section>
</chapter>