Debian Codegraph @

documentation/src/main/asciidoc/ch07.asciidoc

raw
1 [[chapter-xml-configuration]]
2 == Configuring via XML
3
4 So far we have used the default configuration source for Bean Validation, namely annotations.
5 However, there also exist two kinds of XML descriptors allowing configuration via XML. The first
6 descriptor describes general Bean Validation behaviour and is provided as _META-INF/validation.xml_.
7 The second one describes constraint declarations and closely matches the constraint declaration
8 approach via annotations. Let's have a look at these two document types.
9
10 [NOTE]
11 ====
12 The XSD files are available via
13 http://www.jboss.org/xml/ns/javax/validation/configuration/[http://www.jboss.org/xml/ns/javax/validation/configuration] and
14 http://www.jboss.org/xml/ns/javax/validation/mapping[http://www.jboss.org/xml/ns/javax/validation/mapping].
15 ====
16
17 [[section-configuration-validation-xml]]
18 === Configuring the validator factory in _validation.xml_
19
20 The key to enable XML configuration for Hibernate Validator is the file _META-INF/validation.xml_.
21 If this file exists on the classpath its configuration will be applied when the `ValidatorFactory`
22 gets created. <<image-validation-configuration>> shows a model view of the XML schema to which
23 _validation.xml_ has to adhere.
24
25 [[image-validation-configuration]]
26 .Validation configuration schema
27 image::validation-configuration-1.1.png[validation-configuration-1.1.xsd]
28
29 <<example-validation-xml>>
30 shows the several configuration options of _validation.xml_. All settings are optional and the same
31 configuration options are also available programmatically through `javax.validation.Configuration`. In
32 fact the XML configuration will be overridden by values explicitly specified via the programmatic
33 API. It is even possible to ignore the XML configuration completely via
34 `Configuration#ignoreXmlConfiguration()`. See also <<section-configuring-validator-factory>>.
35
36 [[example-validation-xml]]
37 .`validation.xml`
38 ====
39 [source, XML]
40 ----
41 <validation-config
42 xmlns="http://jboss.org/xml/ns/javax/validation/configuration"
43 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
44 xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/configuration">
45
46 <default-provider>com.acme.ValidationProvider</default-provider>
47
48 <message-interpolator>com.acme.MessageInterpolator</message-interpolator>
49 <traversable-resolver>com.acme.TraversableResolver</traversable-resolver>
50 <constraint-validator-factory>
51 com.acme.ConstraintValidatorFactory
52 </constraint-validator-factory>
53 <parameter-name-provider>com.acme.ParameterNameProvider</parameter-name-provider>
54
55 <executable-validation enabled="true">
56 <default-validated-executable-types>
57 <executable-type>CONSTRUCTORS</executable-type>
58 <executable-type>NON_GETTER_METHODS</executable-type>
59 <executable-type>GETTER_METHODS</executable-type>
60 </default-validated-executable-types>
61 </executable-validation>
62
63 <constraint-mapping>META-INF/validation/constraints-car.xml</constraint-mapping>
64
65 <property name="hibernate.validator.fail_fast">false</property>
66 </validation-config>
67 ----
68 ====
69
70 [WARNING]
71 ====
72 There must only be one file named _META-INF/validation.xml_ on the classpath. If more than one is
73 found an exception is thrown.
74 ====
75
76 The node `default-provider` allows to choose the Bean Validation provider. This is useful if there is
77 more than one provider on the classpath. `message-interpolator`, `traversable-resolver`,
78 `constraint-validator-factory` and `parameter-name-provider` allow to customize the used
79 implementations for the interfaces `MessageInterpolator`, `TraversableResolver`,
80 `ConstraintValidatorFactory` and `ParameterNameProvider` defined in the `javax.validation` package.
81 See the sub-sections of <<section-configuring-validator-factory>> for more information about these
82 interfaces.
83
84 `executable-validation` and its subnodes define defaults for method validation. The Bean Validation
85 specification defines constructor and non getter methods as defaults. The enabled attribute acts as
86 global switch to turn method validation on and off (see also <<chapter-method-constraints>>).
87
88 Via the `constraint-mapping` element you can list an arbitrary number of additional XML files
89 containing the actual constraint configuration. Mapping file names must be specified using their
90 fully-qualified name on the classpath. Details on writing mapping files can be found in the next
91 section.
92
93 Last but not least, you can specify provider specific properties via the `property` nodes. In the
94 example we are using the Hibernate Validator specific `hibernate.validator.fail_fast` property (see
95 <<section-fail-fast>>).
96
97 [[section-mapping-xml-constraints]]
98 === Mapping constraints via `constraint-mappings`
99
100 Expressing constraints in XML is possible via files adhering to the schema seen in
101 <<image-mapping-configuration>>. Note that these mapping files are only processed if listed via
102 constraint-mapping in _validation.xml_.
103
104 [[image-mapping-configuration]]
105 .Validation mapping schema
106 image::validation-mapping-1.1.png[validation-mapping-1.1.xsd]
107
108 <<example-constraints-car>> shows how the classes +Car+ and +RentalCar+ from <<example-car>> resp.
109 <<example-rental-car>> could be mapped in XML.
110
111 [[example-constraints-car]]
112 .Bean constraints configured via XML
113 ====
114 [source, XML]
115 ----
116 <constraint-mappings
117 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
118 xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/mapping validation-mapping-1.1.xsd"
119 xmlns="http://jboss.org/xml/ns/javax/validation/mapping" version="1.1">
120
121 <default-package>org.hibernate.validator.referenceguide.chapter05</default-package>
122 <bean class="Car" ignore-annotations="true">
123 <field name="manufacturer">
124 <constraint annotation="javax.validation.constraints.NotNull"/>
125 </field>
126 <field name="licensePlate">
127 <constraint annotation="javax.validation.constraints.NotNull"/>
128 </field>
129 <field name="seatCount">
130 <constraint annotation="javax.validation.constraints.Min">
131 <element name="value">2</element>
132 </constraint>
133 </field>
134 <field name="driver">
135 <valid/>
136 </field>
137 <getter name="passedVehicleInspection" ignore-annotations="true">
138 <constraint annotation="javax.validation.constraints.AssertTrue">
139 <message>The car has to pass the vehicle inspection first</message>
140 <groups>
141 <value>CarChecks</value>
142 </groups>
143 <element name="max">10</element>
144 </constraint>
145 </getter>
146 </bean>
147 <bean class="RentalCar" ignore-annotations="true">
148 <class ignore-annotations="true">
149 <group-sequence>
150 <value>RentalCar</value>
151 <value>CarChecks</value>
152 </group-sequence>
153 </class>
154 </bean>
155 <constraint-definition annotation="org.mycompany.CheckCase">
156 <validated-by include-existing-validators="false">
157 <value>org.mycompany.CheckCaseValidator</value>
158 </validated-by>
159 </constraint-definition>
160 </constraint-mappings>
161 ----
162 ====
163
164 <<example-rental-station-xml>> shows how the constraints from
165 <<example-declaring-parameter-constraints>>, <<example-declaring-return-value-constraints>>
166 and <<example-specifying-constraint-target>> can be expressed in XML.
167
168 [[example-rental-station-xml]]
169 .Method constraints configured via XML
170 ====
171 [source, XML]
172 ----
173 <constraint-mappings
174 xmlns="http://jboss.org/xml/ns/javax/validation/mapping"
175 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
176 xsi:schemaLocation=
177 "http://jboss.org/xml/ns/javax/validation/mapping validation-mapping-1.1.xsd" version="1.1">
178
179 <default-package>org.hibernate.validator.referenceguide.chapter07</default-package>
180
181 <bean class="RentalStation" ignore-annotations="true">
182 <constructor>
183 <return-value>
184 <constraint annotation="ValidRentalStation"/>
185 </return-value>
186 </constructor>
187
188 <constructor>
189 <parameter type="java.lang.String">
190 <constraint annotation="javax.validation.constraints.NotNull"/>
191 </parameter>
192 </constructor>
193
194 <method name="getCustomers">
195 <return-value>
196 <constraint annotation="javax.validation.constraints.NotNull"/>
197 <constraint annotation="javax.validation.constraints.Size">
198 <element name="min">1</element>
199 </constraint>
200 </return-value>
201 </method>
202
203 <method name="rentCar">
204 <parameter type="Customer">
205 <constraint annotation="javax.validation.constraints.NotNull"/>
206 </parameter>
207 <parameter type="java.util.Date">
208 <constraint annotation="javax.validation.constraints.NotNull"/>
209 <constraint annotation="javax.validation.constraints.Future"/>
210 </parameter>
211 <parameter type="int">
212 <constraint annotation="javax.validation.constraints.Min">
213 <element name="value">1</element>
214 </constraint>
215 </parameter>
216 </method>
217 </bean>
218
219 <bean class="Garage" ignore-annotations="true">
220 <method name="buildCar">
221 <parameter type="java.util.List"/>
222 <cross-parameter>
223 <constraint annotation="ELAssert">
224 <element name="expression">...</element>
225 <element name="validationAppliesTo">PARAMETERS</element>
226 </constraint>
227 </cross-parameter>
228 </method>
229 <method name="paintCar">
230 <parameter type="int"/>
231 <return-value>
232 <constraint annotation="ELAssert">
233 <element name="expression">...</element>
234 <element name="validationAppliesTo">RETURN_VALUE</element>
235 </constraint>
236 </return-value>
237 </method>
238 </bean>
239
240 </constraint-mappings>
241 ----
242 ====
243
244 The XML configuration is closely mirroring the programmatic API. For this reason it should suffice
245 to just add some comments. `default-package` is used for all fields where a class name is expected. If
246 the specified class is not fully qualified the configured default package will be used. Every
247 mapping file can then have several bean nodes, each describing the constraints on the entity with
248 the specified class name.
249
250 [WARNING]
251 ====
252 A given class can only be configured once across all configuration files. The same applies for
253 constraint definitions for a given constraint annotation. It can only occur in one mapping file. If
254 these rules are violated a `ValidationException` is thrown.
255 ====
256
257 Setting `ignore-annotations` to `true` means that constraint annotations placed on the configured bean
258 are ignored. The default for this value is true. `ignore-annotations` is also available for the nodes
259 `class`, `fields`, `getter`, `constructor`, `method`, `parameter`, `cross-parameter` and `return-value`.
260 If not explicitly specified on these levels the configured bean value applies.
261
262 The nodes `class`, `field`, `getter`, `constructor` and `method` (and its sub node parameter) determine on
263 which level the constraint gets placed. The `constraint` node is then used to add a constraint on the
264 corresponding level. Each constraint definition must define the class via the `annotation` attribute.
265 The constraint attributes required by the Bean Validation specification (`message`, `groups` and
266 `payload`) have dedicated nodes. All other constraint specific attributes are configured using the
267 `element` node.
268
269 The `class` node also allows to reconfigure the default group sequence (see
270 <<section-default-group-class>>) via the `group-sequence` node. Not shown in the example is the use
271 of `convert-group` to
272 specify group conversions (see <<section-group-conversion>>). This node is available on `field`,
273 `getter`, `parameter` and `return-value` and specifies a from and to attribute to specify the groups.
274
275 Last but not least, the list of `ConstraintValidator` instances associated to a given constraint
276 can be altered via the `constraint-definition` node. The annotation attribute represents the constraint
277 annotation being altered. The `validated-by` element represent the (ordered) list of `ConstraintValidator`
278 implementations associated to the constraint. If `include-existing-validator` is set to `false`,
279 validators defined on the constraint annotation are ignored. If set to `true`, the list of constraint
280 validators described in XML is concatenated to the list of validators specified on the annotation.
281
282 [TIP]
283 ====
284 One use case for constraint-definition is to change the default constraint definition for `@URL`.
285 Historically, Hibernate Validator's default constraint validator for this constraint uses the
286 `java.net.URL` constructor to verify that an URL is valid.
287 However, there is also a purely regular expression based version available which can be configured using
288 XML:
289
290 .Using XML to register a regular expression based constraint definition for `@URL`
291 [source, XML]
292 ----
293 <constraint-definition annotation="org.hibernate.validator.constraints.URL">
294 <validated-by include-existing-validators="false">
295 <value>org.hibernate.validator.constraintvalidators.RegexpURLValidator</value>
296 </validated-by>
297 </constraint-definition>
298 ----
299 ====
300
301
302