forked from beanvalidation/beanvalidation.org
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
9924 lines (9128 loc) · 633 KB
/
index.html
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
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<style type="text/css">
div.added { background-color: #ffff99; }
div.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
div.changed { background-color: #99ff99; }
div.off { }
span.added { background-color: #ffff99; }
span.deleted { text-decoration: line-through;
background-color: #FFDDDD; }
span.changed { background-color: #99ff99; }
span.off { }
</style><title>Bean Validation specification</title><link rel="stylesheet" href="css/html.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="d0e1"></a>Bean Validation specification</h1></div><div><div class="authorgroup"><h3 class="corpauthor">Bean Validation Expert Group</h3><div class="author"><h3 class="author"><span class="firstname">Emmanuel</span> <span class="surname">Bernard</span></h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span></div></div></div></div><div><p class="releaseinfo">1.1.0.Beta3</p></div><div><p class="copyright">Copyright © 2007-2013 Red Hat, Inc</p></div><div><p class="pubdate">2013-02-01</p></div></div><div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#license">Evaluation license</a></span></dt><dt><span class="chapter"><a href="#introduction">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e100">1.1. Expert group</a></span></dt><dt><span class="section"><a href="#d0e232">1.2. Specification goals</a></span></dt><dt><span class="section"><a href="#d0e246">1.3. Required Java version</a></span></dt><dt><span class="section"><a href="#d0e251">1.4. How this document is organized</a></span></dt><dt><span class="section"><a href="#d0e282">1.5. Changes applied since between 1.0 and this draft</a></span></dt><dt><span class="section"><a href="#d0e299">1.6. How to comment</a></span></dt></dl></dd><dt><span class="chapter"><a href="#whatsnew">2. What's new in 1.1</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e312">2.1. Openness</a></span></dt><dt><span class="section"><a href="#d0e322">2.2. Dependency injection</a></span></dt><dt><span class="section"><a href="#d0e339">2.3. Method validation</a></span></dt><dt><span class="section"><a href="#d0e360">2.4. Integration with Context and Dependency Injection</a></span></dt><dt><span class="section"><a href="#d0e365">2.5. Group conversion</a></span></dt><dt><span class="section"><a href="#d0e370">2.6. Message interpolation via the unified expression language</a></span></dt><dt><span class="section"><a href="#d0e375">2.7. Others</a></span></dt></dl></dd><dt><span class="chapter"><a href="#constraintsdefinitionimplementation">3. Constraint Definition</a></span></dt><dd><dl><dt><span class="section"><a href="#constraintsdefinitionimplementation-constraintdefinition">3.1. Constraint annotation</a></span></dt><dd><dl><dt><span class="section"><a href="#constraintsdefinitionimplementation-constraintdefinition-properties">3.1.1. Constraint definition properties</a></span></dt><dd><dl><dt><span class="section"><a href="#constraintsdefinitionimplementation-constraintdefinition-parameters-message">3.1.1.1. message</a></span></dt><dt><span class="section"><a href="#constraintsdefinitionimplementation-constraintdefinition-groups">3.1.1.2. groups</a></span></dt><dt><span class="section"><a href="#constraintsdefinitionimplementation-constraintdefinition-payload">3.1.1.3. payload</a></span></dt><dt><span class="section"><a href="#constraintsdefinitionimplementation-constraintdefinition-validationappliesto">3.1.1.4. validationAppliesTo</a></span></dt><dt><span class="section"><a href="#d0e755">3.1.1.5. Constraint specific parameter</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e763">3.1.2. Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#constraintsdefinitionimplementation-multipleconstraints">3.2. Applying multiple constraints of the same type</a></span></dt><dt><span class="section"><a href="#constraintsdefinitionimplementation-constraintcomposition">3.3. Constraint composition</a></span></dt><dt><span class="section"><a href="#constraintsdefinitionimplementation-validationimplementation">3.4. Constraint validation implementation</a></span></dt><dd><dl><dt><span class="section"><a href="#constraintsdefinitionimplementation-validationimplementation-example">3.4.1. Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#constraintsdefinitionimplementation-constraintfactory">3.5. The ConstraintValidatorFactory</a></span></dt></dl></dd><dt><span class="chapter"><a href="#constraintdeclarationvalidationprocess">4. Constraint declaration and validation process</a></span></dt><dd><dl><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-requirements">4.1. Requirements on classes to be validated</a></span></dt><dd><dl><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-requirements-object">4.1.1. Object validation</a></span></dt><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-requirements-property">4.1.2. Field and property validation</a></span></dt><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-requirements-graphvalidation">4.1.3. Graph validation</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e1726">4.2. Constraint declaration</a></span></dt><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-inheritance">4.3. Inheritance (interface and superclass)</a></span></dt><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-groupsequence">4.4. Group and group sequence</a></span></dt><dd><dl><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-groupsequence-groupinheritance">4.4.1. Group inheritance</a></span></dt><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-groupsequence-groupsequence">4.4.2. Group sequence</a></span></dt><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-groupsequence-redefiningdefaultgroup">4.4.3. Redefining the Default group for a class</a></span></dt><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-groupsequence-implicitgrouping">4.4.4. Implicit grouping</a></span></dt><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-groupsequence-groupconversion">4.4.5. Group conversion</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2341">4.4.5.1. Group conversion examples</a></span></dt></dl></dd><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-groupsequence-formaldefinition">4.4.6. Formal group definitions</a></span></dt></dl></dd><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-methodlevelconstraints">4.5. Method and constructor constraints</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2857">4.5.1. Requirements on methods to be validated</a></span></dt><dt><span class="section"><a href="#d0e2867">4.5.2. Declare parameter constraints</a></span></dt><dd><dl><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-crossparameterconstraints">4.5.2.1. Cross-parameter constraints</a></span></dt><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-methodlevelconstraints-definingparameterconstraints-namingparameters">4.5.2.2. Naming parameters</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e3009">4.5.3. Declaring return value constraints</a></span></dt><dt><span class="section"><a href="#d0e3063">4.5.4. Marking parameters and return values for cascaded
validation</a></span></dt><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-methodlevelconstraints-inheritance">4.5.5. Method constraints in inheritance hierarchies</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e3189">4.5.5.1. Examples</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-validationroutine">4.6. Validation routine</a></span></dt><dd><dl><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-validationroutine-graphvalidation">4.6.1. Object graph validation</a></span></dt><dt><span class="section"><a href="#d0e3512">4.6.2. Method and constructor validation</a></span></dt><dt><span class="section"><a href="#constraintdeclarationvalidationprocess-validationroutine-traversable">4.6.3. Traversable property</a></span></dt><dt><span class="section"><a href="#typevalidatorresolution">4.6.4. ConstraintValidator resolution algorithm</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e4202">4.7. Examples</a></span></dt></dl></dd><dt><span class="chapter"><a href="#validationapi">5. Validation APIs</a></span></dt><dd><dl><dt><span class="section"><a href="#validationapi-validatorapi">5.1. Validator API</a></span></dt><dd><dl><dt><span class="section"><a href="#validationapi-validatorapi-validationmethods">5.1.1. Validation methods</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e4700">5.1.1.1. Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#validationapi-validatorapi-methodlevelvalidationmethods">5.1.2. Methods for validating method and constructor constraints</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e4880">5.1.2.1. Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#validationapi-validatorapi-groups">5.1.3. groups</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e4989">5.1.3.1. Examples</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#validationapi-constraintviolation">5.2. ConstraintViolation</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e5949">5.2.1. Examples</a></span></dt><dt><span class="section"><a href="#d0e6008">5.2.2. Examples for method/constructor constraint violations</a></span></dt></dl></dd><dt><span class="section"><a href="#validationapi-message">5.3. Message interpolation</a></span></dt><dd><dl><dt><span class="section"><a href="#default-messageresolver">5.3.1. Default message interpolation</a></span></dt><dd><dl><dt><span class="section"><a href="#default-resolution-algorithm">5.3.1.1. Default message interpolation algorithm</a></span></dt><dt><span class="section"><a href="#message-interpolation-default-locale">5.3.1.2. Locale for default message interpolation</a></span></dt><dt><span class="section"><a href="#d0e6247">5.3.1.3. Message expressions using Expression
Language (EL)</a></span></dt></dl></dd><dt><span class="section"><a href="#custom-message-resolution">5.3.2. Custom message interpolation</a></span></dt><dt><span class="section"><a href="#validationapi-message-examples">5.3.3. Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#validationapi-triggeringmethodvalidation">5.4. Triggering method validation</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e6603">5.4.1. PROPOSAL: customizing method interception</a></span></dt></dl></dd><dt><span class="section"><a href="#bootstrapping">5.5. Bootstrapping</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e6771">5.5.1. Examples</a></span></dt><dt><span class="section"><a href="#d0e6847">5.5.2. ValidatorFactory</a></span></dt><dt><span class="section"><a href="#d0e7065">5.5.3. Configuration</a></span></dt><dt><span class="section"><a href="#d0e7480">5.5.4. ValidationProvider and ValidationProviderResolver</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e7490">5.5.4.1. ValidationProviderResolver</a></span></dt><dt><span class="section"><a href="#id-bootstrap-validationprovider">5.5.4.2. ValidationProvider</a></span></dt></dl></dd><dt><span class="section"><a href="#boostrapping-validation">5.5.5. Validation</a></span></dt><dt><span class="section"><a href="#xml-config">5.5.6. XML Configuration: META-INF/validation.xml</a></span></dt><dt><span class="section"><a href="#bootstrapping-usageandcontainerexpectation">5.5.7. Bootstrapping considerations</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#constraintmetadata">6. Constraint metadata request APIs</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e8064">6.1. Validator</a></span></dt><dt><span class="section"><a href="#constraintmetadata-elementdescriptor">6.2. ElementDescriptor</a></span></dt><dt><span class="section"><a href="#d0e8266">6.3. BeanDescriptor</a></span></dt><dt><span class="section"><a href="#d0e8355">6.4. CascadableDescriptor</a></span></dt><dt><span class="section"><a href="#d0e8390">6.5. GroupConversionDescriptor</a></span></dt><dt><span class="section"><a href="#d0e8415">6.6. PropertyDescriptor</a></span></dt><dt><span class="section"><a href="#d0e8450">6.7. ExecutableDescriptor, MethodDescriptor and
ConstructorDescriptor</a></span></dt><dt><span class="section"><a href="#d0e8548">6.8. ParameterDescriptor</a></span></dt><dt><span class="section"><a href="#d0e8574">6.9. ReturnValueDescriptor</a></span></dt><dt><span class="section"><a href="#constraintmetadata-constraintdescriptor">6.10. ConstraintDescriptor</a></span></dt><dt><span class="section"><a href="#d0e8676">6.11. Example</a></span></dt></dl></dd><dt><span class="chapter"><a href="#builtinconstraints">7. Built-in Constraint definitions</a></span></dt><dt><span class="chapter"><a href="#xml">8. XML deployment descriptor</a></span></dt><dd><dl><dt><span class="section"><a href="#xml-mapping">8.1. Constraint definition and declaration</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e8853">8.1.1. Constraint declaration in XML</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e8901">8.1.1.1. Class-level overriding</a></span></dt><dt><span class="section"><a href="#d0e8950">8.1.1.2. Field-level overriding</a></span></dt><dt><span class="section"><a href="#d0e9029">8.1.1.3. Property-level overriding</a></span></dt><dt><span class="section"><a href="#xml-mapping-constraintdeclarationinxml-constructorleveloverriding">8.1.1.4. Constructor-level overriding</a></span></dt><dt><span class="section"><a href="#xml-mapping-constraintdeclarationinxml-methodleveloverriding">8.1.1.5. Method-level overriding</a></span></dt><dt><span class="section"><a href="#d0e9404">8.1.1.6. Constraint declaration</a></span></dt><dt><span class="section"><a href="#d0e9511">8.1.1.7. Declaration of group conversions</a></span></dt></dl></dd><dt><span class="section"><a href="#xml-mapping-constraintdefinition">8.1.2. Overriding constraint definitions in XML</a></span></dt><dt><span class="section"><a href="#xml-mapping-typeconversion">8.1.3. Converting the string representation of a value</a></span></dt><dt><span class="section"><a href="#xml-mapping-xsd">8.1.4. XML Schema</a></span></dt></dl></dd><dt><span class="section"><a href="#xml-config-xsd">8.2. Configuration schema</a></span></dt></dl></dd><dt><span class="chapter"><a href="#exception">9. Exception model</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e9874">9.1. Error report:
ConstraintViolationException</a></span></dt><dt><span class="section"><a href="#d0e9916">9.2. Constraint definition:
ConstraintDefinitionException</a></span></dt><dt><span class="section"><a href="#d0e9939">9.3. Constraint declaration:
ConstraintDeclarationException and
UnexpectedTypeException</a></span></dt><dt><span class="section"><a href="#d0e9988">9.4. Group definition:
GroupDefinitionException</a></span></dt></dl></dd><dt><span class="chapter"><a href="#integration">10. Integration</a></span></dt><dd><dl><dt><span class="section"><a href="#integration-general">10.1. General requirements</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e10020">10.1.1. Objects lifecycle</a></span></dt><dt><span class="section"><a href="#integration-general-executable">10.1.2. Method and constructor validation</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e10263">10.1.2.1. Examples</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#integration-javaee">10.2. Java EE</a></span></dt><dt><span class="section"><a href="#d0e10358">10.3. Context and Dependency Injection (CDI)
integration</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e10363">10.3.1. ValidatorFactory and
Validator</a></span></dt><dt><span class="section"><a href="#d0e10470">10.3.2. ConstraintValidatorFactory,
MessageInterpolator,
ParameterNameProvider and
TraversableResolver</a></span></dt><dt><span class="section"><a href="#d0e10566">10.3.3. Method validation</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e10582">10.4. Java Persistence 2.0 integration</a></span></dt><dt><span class="section"><a href="#d0e10590">10.5. Java Server Faces 2.0 integration</a></span></dt><dt><span class="section"><a href="#d0e10598">10.6. JAX-RS 2 integration</a></span></dt></dl></dd><dt><span class="appendix"><a href="#terminology">A. Terminology</a></span></dt><dt><span class="appendix"><a href="#standard-resolver-messages">B. Standard ResourceBundle messages</a></span></dt><dt><span class="appendix"><a href="#appendix-jpa">C. Java Persistence 2.0 and schema generation</a></span></dt><dt><span class="appendix"><a href="#changelog">D. Changelog</a></span></dt></dl></div><div class="preface" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="license"></a>Evaluation license</h2></div></div><div></div></div><p>Copyright 2007-2013 Red Hat Inc.</p><p>All rights reserved.</p><p>NOTICE</p><p>The Specification is protected by copyright and the information
described therein may be protected by one or more U.S. patents, foreign
patents, or pending applications. Except as provided under the following
license, no part of the Specification may be reproduced in any form by any
means without the prior written authorization of Red Hat Inc. and its
licensors, if any. Any use of the Specification and the information
described therein will be governed by the terms and conditions of this
Agreement.</p><p>Subject to the terms and conditions of this license, including your
compliance with Paragraphs 1 and 2 below, Red Hat Inc. hereby grants you a
fully-paid, non-exclusive, non-transferable, limited license (without the
right to sublicense) under Red Hat Inc.'s intellectual property rights
to:</p><p>1. Review the Specification for the purposes of evaluation. This
includes: (i) developing implementations of the Specification for your
internal, non-commercial use; (ii) discussing the Specification with any
third party; and (iii) excerpting brief portions of the Specification in
oral or written communications which discuss the Specification provided that
such excerpts do not in the aggregate constitute a significant portion of
the Specification.</p><p>2. Distribute implementations of the Specification to third parties
for their testing and evaluation use, provided that any such
implementation:</p><p>(i) does not modify, subset, superset or otherwise extend the Licensor
Name Space, or include any public or protected packages, classes, Java
interfaces, fields or methods within the Licensor Name Space other than
those required/authorized by the Specification or Specifications being
implemented;</p><p>(ii) is clearly and prominently marked with the word "UNTESTED" or
"EARLY ACCESS" or "INCOMPATIBLE" or "UNSTABLE" or "BETA" in any list of
available builds and in proximity to every link initiating its download,
where the list or link is under Licensee's control; and</p><p>(iii) includes the following notice:</p><p>"This is an implementation of an early-draft specification developed
under the Java Community Process (JCP). The code is not compatible with any
specification of the JCP."</p><p>The grant set forth above concerning your distribution of
implementations of the Specification is contingent upon your agreement to
terminate development and distribution of your implementation of early draft
upon final completion of the Specification. If you fail to do so, the
foregoing grant shall be considered null and void.</p><p>No provision of this Agreement shall be understood to restrict your
ability to make and distribute to third parties applications written to the
Specification.</p><p>Other than this limited license, you acquire no right, para or
interest in or to the Specification or any other Red Hat Inc. intellectual
property, and the Specification may only be used in accordance with the
license terms set forth herein. This license will expire on the earlier of:
(a) two (2) years from the date of Release listed above; (b) the date on
which the final version of the Specification is publicly released; or (c)
the date on which the Java Specification Request (JSR) to which the
Specification corresponds is withdrawn. In addition, this license will
terminate immediately without notice from Red Hat Inc. if you fail to comply
with any provision of this license. Upon termination, you must cease use of
or destroy the Specification.</p><p>"Licensor Name Space" means the public class or interface declarations
whose names begin with "java", "javax", "com.redhat", "com.jboss",
"org.jboss", "org.hibernate" or their equivalents in any subsequent naming
convention adopted through the Java Community Process, or any recognized
successors or replacements thereof.</p><p>TRADEMARKS</p><p>No right, para, or interest in or to any trademarks, service marks, or
trade names of Red Hat Inc. or Red Hat's licensors is granted hereunder.
Java and Java-related logos, marks and names are trademarks or registered
trademarks of Sun Microsystems, Inc. in the U.S. and other countries.</p><p>DISCLAIMER OF WARRANTIES</p><p>THE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY
CONTAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY RED
HAT Inc. RED HAT Inc. MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CONTENTS OF
THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR
IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS,
COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent
any commitment to release or implement any portion of the Specification in
any product.</p><p>THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR
TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION
THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE
SPECIFICATION, IF ANY. RED HAT Inc. MAY MAKE IMPROVEMENTS AND/OR CHANGES TO
THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY
TIME. Any use of such changes in the Specification will be governed by the
then-current license for the applicable version of the Specification.</p><p>LIMITATION OF LIABILITY</p><p>TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL RED HAT Inc. OR
ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST
REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL,
INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY
OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRACTICING,
MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF RED HAT Inc. AND/OR ITS
LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.</p><p>You will hold Red Hat Inc. (and its licensors) harmless from any
claims based on your use of the Specification for any purposes other than
the limited right of evaluation as described above, and from any claims that
later versions or releases of any Specification furnished to you are
incompatible with the Specification provided to you under this
license.</p><p>RESTRICTED RIGHTS LEGEND</p><p>If this Software is being acquired by or on behalf of the U.S.
Government or by a U.S. Government prime contractor or subcontractor (at any
tier), then the Government's rights in the Software and accompanying
documentation shall be only as set forth in this license; this is in
accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of
Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD
acquisitions).</p><p>REPORT</p><p>You may wish to report any ambiguities, inconsistencies or
inaccuracies you may find in connection with your evaluation of the
Specification ("Feedback"). To the extent that you provide Red Hat Inc. with
any Feedback, you hereby: (i) agree that such Feedback is provided on a
non-proprietary and non-confidential basis, and (ii) grant Red Hat Inc. a
perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license,
with the right to sublicense through multiple levels of sublicensees, to
incorporate, disclose, and use without limitation the Feedback for any
purpose related to the Specification and future versions, implementations,
and test suites thereof.</p><p>GENERAL TERMS</p><p>Any action related to this Agreement will be governed by California
law and controlling U.S. federal law. The U.N. Convention for the
International Sale of Goods and the choice of law rules of any jurisdiction
will not apply.</p><p>The Specification is subject to U.S. export control laws and may be
subject to export or import regulations in other countries. Licensee agrees
to comply strictly with all such laws and regulations and acknowledges that
it has the responsibility to obtain such licenses to export, re-export or
import as may be required after delivery to Licensee.</p><p>This Agreement is the parties' entire agreement relating to its
subject matter. It supersedes all prior or contemporaneous oral or written
communications, proposals, conditions, representations and warranties and
prevails over any conflicting or additional terms of any quote, order,
acknowledgment, or other communication between the parties relating to its
subject matter during the term of this Agreement. No modification to this
Agreement will be binding, unless in writing and signed by an authorized
representative of each party.</p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="introduction"></a>Chapter 1. Introduction</h2></div></div><div></div></div><p>This document is the specification of the Java API for JavaBean
validation in Java EE and Java SE. The technical objective of this work is
to provide an object level constraint declaration and validation facility
for the Java application developer, as well as a constraint metadata
repository and query API.</p><p>It also offers method and constructor validation facilities to ensure
constraints on their parameters and return values.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e100"></a>1.1. Expert group</h2></div></div><div></div></div><div class="changed"><p>This work is being conducted as part of JSR
349 and formerly JSR 303 under the Java Community Process Program. This
specification is the result of the collaborative work of the members of
the JSR 349 Expert Group and the community at large. The following persons
have actively contributed to Bean Validation 1.1 in alphabetical
order:</p></div><div class="added"><div class="itemizedlist"><ul type="disc"><li><p>Matt Benson</p></li><li><p>Paul Benedict</p></li><li><p>Emmanuel Bernard (Red Hat, Inc.) - Specification Lead</p></li><li><p>Edward Burns (Oracle)</p></li><li><p>Peter Davis</p></li><li><p>Linda DeMichiel (Oracle)</p></li><li><p>Hardy Ferentschik (Red Hat, Inc.)</p></li><li><p>Antonio Goncalves</p></li><li><p>Cemalettin Koç</p></li><li><p>Rich Midwinter</p></li><li><p>Gunnar Morling (individual then Red Hat, Inc.)</p></li><li><p>Pete Muir (Red Hat, Inc.)</p></li><li><p>Michael Nascimento Santos</p></li><li><p>Gerhard Petracek</p></li><li><p>Kevin Pollet (SERLI)</p></li><li><p>Jagadish Prasath Ramu (Oracle)</p></li><li><p>Bill Shannon (Oracle)</p></li><li><p>Sebastian Thomschke</p></li></ul></div></div><div class="changed"><p>Former expert group members of JSR-303 in
alphabetical order are:</p></div><div class="itemizedlist"><ul type="disc"><li><p>Geert Bevin</p></li><li><p>Emmanuel Bernard (Red Hat, Inc.) - Specification Lead</p></li><li><p>Uri Boness</p></li><li><p>Erik Brakkee (Ericsson AB)</p></li><li><p>Ed Burns (Sun Microsystems, Inc.)</p></li><li><p>Jason Carreira</p></li><li><p>Robert Clevenger (Oracle - retired)</p></li><li><p>Linda DeMichiel (Sun Microsystems, Inc.)</p></li><li><p>Tim Fennel</p></li><li><p>Bharath Ganesh (Pramati Technologies)</p></li><li><p>Romain Guy (Google Inc.)</p></li><li><p>Robert Harrop</p></li><li><p>Jacob J. Hookom</p></li><li><p>Bob Lee (Google Inc.)</p></li><li><p>Craig R. McClanahan (Sun Microsystems, Inc.)</p></li><li><p>Niall K. Pemberton</p></li><li><p>Steve Peterson</p></li><li><p>Dhanji R. Prasanna (Google Inc., formerly individual)</p></li><li><p>Gerhard Petracek</p></li><li><p>Matt Raible</p></li><li><p>Michael Nascimento Santos</p></li><li><p>Sebastian Thomschke</p></li><li><p>Jon Wetherbee (Oracle)</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e232"></a>1.2. Specification goals</h2></div></div><div></div></div><p>Validating data is a common task that occurs throughout an
application, from the presentation layer to the persistence layer. Often
the same validation logic is implemented in each layer, proving to be time
consuming and error-prone. To avoid duplication of these validations in
each layer, developers often bundle validation logic directly into the
domain model, cluttering domain classes with validation code that is, in
fact, metadata about the class itself.</p><p>This JSR defines a metadata model and API for JavaBean validation.
The default metadata source is annotations, with the ability to override
and extend the meta-data through the use of XML validation
descriptors.</p><p>The validation API developed by this JSR is not intended for use in
any one tier or programming model. It is specifically not tied to either
the web tier or the persistence tier, and is available for both
server-side application programming, as well as rich client Swing
application developers. This API is seen as a general extension to the
JavaBeans object model, and as such is expected to be used as a core
component in other specifications. Ease of use and flexibility have
influenced the design of this specification.</p><div class="added"><p>As of version 1.1, Bean Validation constraints
can also be applied to the parameters and return values of methods of
arbitrary Java types. Thus the Bean Validation API can be used to describe
and validate the contract (comprising pre- and postconditions) applying to
a given method ("Programming by Contract", PbC). Note that it is
<span class="emphasis"><em>not</em></span> the goal of this specification to develop a
fully-fledged PbC solution but rather an easy-to-use facility satisfying
the most common needs related to applying constraints to method parameters
and return values, based on the proven concepts of the Bean Validation
API.</p></div></div><div class="added"><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e246"></a>1.3. Required Java version</h2></div></div><div></div></div><p>The specification uses Java 6.0 language features. There is no
requirement that implementations be compatible with Java language versions
prior to 6.0.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e251"></a>1.4. How this document is organized</h2></div></div><div></div></div><p>This document describes each aspect of the bean validation
specification in a separate chapter. One should remember that the
specification is a consistent whole.</p><p><a href="#constraintsdefinitionimplementation" title="Chapter 3. Constraint Definition">Chapter 3, <i>Constraint Definition</i></a> describes how
constraints are defined.</p><p><a href="#constraintdeclarationvalidationprocess" title="Chapter 4. Constraint declaration and validation process">Chapter 4, <i>Constraint declaration and validation process</i></a> describes
how a JavaBean class is decorated with annotations to describe
constraints.</p><p><a href="#validationapi" title="Chapter 5. Validation APIs">Chapter 5, <i>Validation APIs</i></a> describes how to programmatically
validate a JavaBean.</p><p><a href="#constraintmetadata" title="Chapter 6. Constraint metadata request APIs">Chapter 6, <i>Constraint metadata request APIs</i></a> describes how the metadata
query API works.</p><p><a href="#builtinconstraints" title="Chapter 7. Built-in Constraint definitions">Chapter 7, <i>Built-in Constraint definitions</i></a> list all the built-in
constraints.</p><div class="added"><p><a href="#integration" title="Chapter 10. Integration">Chapter 10, <i>Integration</i></a> describes the
different integration points of Bean Validation with other technologies.
In some cases one has to refer to the to the respective specifications for
the up-to-date integration rules.</p></div><p>In <a href="#terminology" title="Appendix A. Terminology">Appendix A, <i>Terminology</i></a>, key concepts are summarized. Some
reviewers have found that reading the terminology section first helps to
better understand the specification.</p><p>The changelog can be found at <a href="#changelog" title="Appendix D. Changelog">Appendix D, <i>Changelog</i></a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e282"></a>1.5. Changes applied since between 1.0 and this draft</h2></div></div><div></div></div><p>To facilitate change reviews, HTML rendering of this specification
highlight changes:</p><div class="itemizedlist"><ul type="disc"><li><div class="added"><p>Added paragraphs are being highlighted in green</p></div></li><li><div class="changed"><p>Changed paragraphs are being highlighted in yellow</p></div></li><li><div class="deleted"><p>Deleted paragraphs are being highlighted in red and stroke -
note that some elements might be deleted without this notice.</p></div></li></ul></div><p>At this time change highlighting is not supported in the PDF
version.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e299"></a>1.6. How to comment</h2></div></div><div></div></div><div class="changed"><p>The expert group is eager to receive feedback
from readers. Feel free to contact us. You can get all the details at
<a href="http://beanvalidation.org/contribute/" target="_top">http://beanvalidation.org/contribute/</a>.</p></div></div></div><div class="added"><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="whatsnew"></a>Chapter 2. What's new in 1.1</h2></div></div><div></div></div><p>Bean Validation 1.1 improves and build upon Bean Validation 1.0. The
expert group and the community have been working of a few specific
areas.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e312"></a>2.1. Openness</h2></div></div><div></div></div><p>All of Bean Validation 1.1 work has been done in the open and in an
open source way. Source code for the API, reference implementation, test
compatibility kit as well as the specification and the website source are
available in the open. All discussions are done in the open in the
publicly available development mailing list. Road map and proposals are
also published on the website.</p><p>You can find all the details (mailing lists, source repositories
etc) at <a href="http://beanvalidation.org" target="_top">http://beanvalidation.org</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e322"></a>2.2. Dependency injection</h2></div></div><div></div></div><p>Bean Validation uses a few components
<tt class="classname">MessageInterpolator</tt>,
<tt class="classname">TraversableResolver</tt>,
<tt class="classname">ConstraintValidatorFactory</tt> and
<tt class="classname">ConstraintValidator</tt>. We aim at standardising how
these objects are managed by a container and how these objects can benefit
from container services. In particular, CDI support within Java EE is
being defined.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e339"></a>2.3. Method validation</h2></div></div><div></div></div><p>Bean Validation 1.1 allows to put constraints to the parameters and
return values of arbitrary methods and constructors. That way the Bean
Validation API can be used to describe and validate the contract applying
to a given method or constructor, that is</p><div class="itemizedlist"><ul type="disc"><li><p>the preconditions that must be met by the caller before the
method or constructor may be invoked and</p></li><li><p>the postconditions that are guaranteed to the caller after a
method or constructor invocation returns.</p></li></ul></div><p>This enables a programming style known as "Programming by Contract"
(PbC). Compared to traditional means of checking the sanity of argument
and return values this approach has several advantages:</p><div class="itemizedlist"><ul type="disc"><li><p>These checks are expressed declaratively and don't have to be
performed manually, which results in less code to write, read and
maintain.</p></li><li><p>The pre- and postconditions applying for a method or constructor
don't have to be expressed again in the documentation, since any of
it's annotations will automatically be included in the generated
JavaDoc. This reduces redundancies, thus avoiding efforts and
inconsistencies between implementation and documentation.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e360"></a>2.4. Integration with Context and Dependency Injection</h2></div></div><div></div></div><p>The integration points with Context and Dependency Injection (CDI)
have been increased and reworked. This should open up for a more natural
and standard integration both in Java EE and Java SE and encompass
dependency injection, component lifecycle management and interception for
method validation.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e365"></a>2.5. Group conversion</h2></div></div><div></div></div><p>The specification offers a way to alter the targeted group when
validation cascading in happening. This feature is particularly useful to
reuse a given object (graph) and to avoid leaking group segmentation from
various object subgraphs. It also makes for more readable
constraints.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e370"></a>2.6. Message interpolation via the unified expression language</h2></div></div><div></div></div><p>Constraint violation messages can now use EL expressions for a much
more flexible rendering and string formatting. In particular a formatter
object is injected in the EL context to convert numbers dates etc into the
locale specific string representation. Likewise, the validated value is
also available in the EL context.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e375"></a>2.7. Others</h2></div></div><div></div></div><p>Many more minor changes are being done. Check out the change log for
more details at <a href="#changelog" title="Appendix D. Changelog">Appendix D, <i>Changelog</i></a>.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="constraintsdefinitionimplementation"></a>Chapter 3. Constraint Definition</h2></div></div><div></div></div><p>Constraints are defined by the combination of a constraint annotation
and a list of constraint validation implementations. The constraint
annotation is applied on types, methods, fields or other constraint
annotations in case of composition.</p><p>Unless stated otherwise the default package name for the Bean
Validation APIs is <tt class="classname">javax.validation</tt>.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="constraintsdefinitionimplementation-constraintdefinition"></a>3.1. Constraint annotation</h2></div></div><div></div></div><p>A constraint on a JavaBean is expressed through one or more
annotations. <span class="tck-not-testable">An annotation is considered a
<span class="added"><span>generic</span></span> constraint definition if its
retention policy contains <tt class="literal">RUNTIME</tt> and if the annotation
itself is annotated with
<tt class="literal">javax.validation.Constraint</tt></span>.</p><pre class="programlisting">/**
* Link between a constraint annotation and its constraint validation implementations.
* <p/>
* A given constraint annotation should be annotated by a {@code @Constraint}
* annotation which refers to its list of constraint validation implementations.
*
* @author Emmanuel Bernard
* @author Gavin King
* @author Hardy Ferentschik
*/
@Documented
@Target({ ANNOTATION_TYPE })
@Retention(RUNTIME)
public @interface Constraint {
/**
* {@code ConstraintValidator} classes must reference distinct target types.
* If two {@code ConstraintValidator}s refer to the same type,
* an exception will occur.
*
* @return array of (@code ConstraintValidator} classes implementing the constraint
*/
Class<? extends ConstraintValidator<?, ?>>[] validatedBy();
}</pre><div class="added"><p class="tck-not-testable">An annotation is
considered a cross-parameter constraint definition (see section <a href="#constraintdeclarationvalidationprocess-crossparameterconstraints" title="4.5.2.1. Cross-parameter constraints">Section 4.5.2.1, “Cross-parameter constraints”</a>)
if its retention policy contains <tt class="literal">RUNTIME</tt> and if the
annotation itself is annotated with
<tt class="literal">javax.validation.CrossParameterConstraint</tt>.</p></div><div class="added"><pre class="programlisting">/**
* Link between a cross-parameter constraint annotation and its constraint
* validation implementation.
*
* @author Gunnar Morling
*/
@Documented
@Target({ ANNOTATION_TYPE })
@Retention(RUNTIME)
public @interface CrossParameterConstraint {
/**
* Returns the {@link ConstraintValidator} class for the annotated
* cross-parameter constraint. The validator's type parameter {@code T} must
* resolve to {@code Object[]}.
*
* @return Constraint validator class implementing the constraint
*/
Class<? extends ConstraintValidator<?, ?>> validatedBy();
}</pre></div><div class="added"><p>A Bean Validation constraint is most of the
time either a generic constraint (marked with
<tt class="classname">@Constraint</tt>) or a cross-parameter constraint
(marked with <tt class="classname">@CrossParameterConstraint</tt>). In rare
situations, a constraint can be both.</p></div><div class="added"><i><span class="remark">TODO: An alternative to @Constraint /
@CrossParameterConstraint is to annotate the ConstraintValidator with a
@Validates annotation. @Validates({ANNOTATED_ELEMENT, CROSS_PARAMETER}), A
ConstraintValidator will by default validate the annotated element but can
be marked as validating cross parameters or both.</span></i></div><div class="added"><p>A generic constraint is used when validating a
bean, a field, a getter, a method/constructor return value or a
method/constructor parameter. A cross-parameter constraint is used when
validating the consistency of several method/constructor
parameters.</p></div><p class="tck-not-testable">Generic constraint annotations can target
any of the following <tt class="classname">ElementType</tt>s:</p><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">FIELD</tt> for constrained attributes</p></li><li><p><tt class="literal">METHOD</tt> for constrained getters<span class="added"><span> and constrained method return
values</span></span></p></li><li><div class="added"><p><tt class="classname">CONSTRUCTOR</tt> for constrained constructor
return values</p></div></li><li><div class="added"><p><tt class="classname">PARAMETER</tt> for constrained method and
constructor parameters</p></div></li><li><p><tt class="literal">TYPE</tt> for constrained beans</p></li><li><p><tt class="literal">ANNOTATION_TYPE</tt> for constraints composing
other constraints</p></li></ul></div><div class="added"><p class="tck-not-testable">Cross-parameter
constraint annotations can target any of the following
<tt class="classname">ElementType</tt>s: </p><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">METHOD</tt></p></li><li><p><tt class="literal">CONSTRUCTOR</tt></p></li><li><p><tt class="literal">ANNOTATION_TYPE</tt> for cross-parameter
constraints composing other cross-parameter constraints</p></li></ul></div></div><div class="added"><p class="tck-testable">A constraint annotation
that is both can target the union of the generic and cross-parameter
constraint annotations targets.</p></div><p>While other <tt class="classname">ElementType</tt>s are not forbidden,
the provider does not have to recognize and process constraints placed on
such types. <span class="deleted"><span>Built-in types do support
<tt class="literal">PARAMETER</tt> and <tt class="literal">CONSTRUCTOR</tt> to allow
Bean Validation provider specific extensions. It is considered good
practice to follow the same approach for custom
annotations.</span></span></p><p>Since a given constraint definition applies to one or more specific
Java types, the JavaDoc for the constraint annotation should clearly state
which types are supported. <span class="tck-testable">Applying a
constraint annotation to an incompatible type will raise an
<tt class="classname">UnexpectedTypeException</tt>.</span> Care should be
taken on defining the list of <tt class="classname">ConstraintValidator</tt>s.
The type resolution algorithm (see <a href="#typevalidatorresolution" title="4.6.4. ConstraintValidator resolution algorithm">Section 4.6.4, “ConstraintValidator resolution algorithm”</a>) could lead to exceptions if the
<tt class="classname">ConstraintValidator</tt> list leads to
ambiguities.</p><div class="added"><p>Likewise, the JavaDoc should clearly state if
the constraint is a generic and / or a cross-parameter constraint.</p></div><p><span class="tck-testable">If a constraint definition is not valid,
a <tt class="classname">ConstraintDefinitionException</tt> is raised either at
validation time or when the metadata is requested.</span> Invalid
constraint definitions causes are multiple but include missing or illegal
<tt class="methodname">message</tt> or <tt class="methodname">groups</tt>
elements (see <a href="#constraintsdefinitionimplementation-constraintdefinition-properties" title="3.1.1. Constraint definition properties">Section 3.1.1, “Constraint definition properties”</a>).</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="constraintsdefinitionimplementation-constraintdefinition-properties"></a>3.1.1. Constraint definition properties</h3></div></div><div></div></div><p><span class="tck-testable">A constraint definition may have
attributes that are specified at the time the constraint is applied to a
JavaBean.</span> The properties are mapped as annotation elements. The
annotation element names <tt class="literal">message</tt>,
<tt class="literal">groups</tt>, <span class="added"><tt class="literal">validationAppliesTo</tt></span> and
<tt class="literal">payload</tt> are considered reserved names; <span class="tck-testable">annotation elements starting with
<tt class="literal">valid</tt> are not allowed</span>; a constraint may use
any other element name for its attributes.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="constraintsdefinitionimplementation-constraintdefinition-parameters-message"></a>3.1.1.1. message</h4></div></div><div></div></div><p class="tck-testable">Every constraint annotation must define a
<tt class="literal">message</tt> element of type
<tt class="literal">String</tt>.</p><pre class="programlisting">String message() default "{com.acme.constraint.MyConstraint.message}";</pre><p>The <tt class="methodname">message</tt> element value is used to
create the error message. See <a href="#validationapi-message" title="5.3. Message interpolation">Section 5.3, “Message interpolation”</a>
for a detailed explanation. It is recommended to default
<tt class="literal">message</tt> values to resource bundle keys to enable
internationalization. It is also recommended to use the following
convention: the resource bundle key should be the fully qualified
class name of the constraint annotation concatenated to
<tt class="literal">.message</tt> as shown in the previous program
listing.</p><p>Built-in Bean Validation constraints follow this
convention.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="constraintsdefinitionimplementation-constraintdefinition-groups"></a>3.1.1.2. groups</h4></div></div><div></div></div><p><span class="tck-testable">Every constraint annotation must
define a <tt class="literal">groups</tt> element that specifies the
processing groups with which the constraint declaration is
associated.</span><span class="added"><span class="tck-testable">The type of the groups parameter is
<tt class="classname">Class<?>[]</tt>.</span></span></p><pre class="programlisting"> Class<?>[] groups() default {};</pre><p class="tck-testable">The default value must be an empty
array.</p><p class="tck-testable">If no group is specified when declaring the
constraint on an element, the <tt class="literal">Default</tt> group is
considered declared.</p><p>See <a href="#validationapi-validatorapi-groups" title="5.1.3. groups">Section 5.1.3, “groups”</a> for more
information.</p><p>Groups are typically used to control the order in which
constraints are evaluated, or to perform validation of the partial
state of a JavaBean.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="constraintsdefinitionimplementation-constraintdefinition-payload"></a>3.1.1.3. payload</h4></div></div><div></div></div><p class="tck-testable">Constraint annotations must define a
<tt class="literal">payload</tt> element that specifies the payload with
which the the constraint declaration is associated.</p><pre class="programlisting"> Class<? extends Payload>[] payload() default {};</pre><p class="tck-testable">The default value must be an empty
array.</p><p class="tck-testable">Each attachable payload extends
<tt class="classname">Payload</tt>.</p><pre class="programlisting">/**
* Payload type that can be attached to a given
* constraint declaration.
* Payloads are typically used to carry on metadata information
* consumed by a validation client.
*
* Use of payloads is not considered portable.
*
* @author Emmanuel Bernard
* @author Gerhard Petracek
*/
public interface Payload {
}</pre><p>Payloads are typically used by validation clients to associate
some metadata information with a given constraint declaration.
Payloads are typically non-portable. Describing payloads as interface
extensions as opposed to a string-based approach allows an easier and
more type-safe approach.</p><p>One use case for payload shown in <a href="#example-payload" title="Example 3.1. Use of payload to associate severity to a constraint">Example 3.1, “Use of payload to associate severity to a constraint”</a> is to associate a severity to a
constraint. This severity can be exploited by a presentation framework
to adjust how a constraint failure is displayed.</p><div class="example"><a name="example-payload"></a><p class="title"><b>Example 3.1. Use of payload to associate severity to a constraint</b></p><pre class="programlisting">package com.acme.severity;
public class Severity {
public static class Info implements Payload {};
public static class Error implements Payload {};
}
public class Address {
@NotNull(message="would be nice if we had one", payload=Severity.Info.class)
public String getZipCode() {...}
@NotNull(message="the city is mandatory", payload=Severity.Error.class)
String getCity() {...}
}</pre></div><p>The <tt class="literal">payload</tt> information can be retrieved from
error reports via the <tt class="classname">ConstraintDescriptor</tt>
either accessed through the <tt class="classname">ConstraintViolation</tt>
objects (see <a href="#validationapi-constraintviolation" title="5.2. ConstraintViolation">Section 5.2, “ConstraintViolation”</a>) or
through the metadata API (see <a href="#constraintmetadata-constraintdescriptor" title="6.10. ConstraintDescriptor">Section 6.10, “ConstraintDescriptor”</a>).</p></div><div class="added"><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="constraintsdefinitionimplementation-constraintdefinition-validationappliesto"></a>3.1.1.4. validationAppliesTo</h4></div></div><div></div></div><p><tt class="literal">validationAppliesTo</tt> is used at constraint
declaration time to clarify what the constraint targets (ie. the
annotated element, the method return value or the method
parameters).</p><p><span>The element
<tt class="literal">validationAppliesTo</tt> must only be present for
constraints that are both generic and cross-parameter, it is mandatory
in this situation. A
<tt class="classname">ConstraintDefinitionException</tt> is raised if
these rules are violated.</span></p><div class="example"><a name="d0e682"></a><p class="title"><b>Example 3.2. validationAppliesTo and ConstraintTarget</b></p><pre class="programlisting"> ConstraintTarget validationAppliesTo() default ConstraintTarget.IMPLICIT;</pre><pre class="programlisting">/**
* Defines the constraint target
*
* @author Emmanuel Bernard <[email protected]>
* @since 1.1
*/
public enum ConstraintTarget {
/**
* Discover the type when no ambiguity is present
* <ul>
* <li>if neither on a method nor a constructor, it implies the annotated element (type, field etc).</li>
* <li>if on a method or constructor with no parameter, it implies {@code RETURN_VALUE}</li>
* <li>if on a method with no return value ({@code void}), it implies {@code PARAMETERS}</li>
* </ul>
* Otherwise, {@code IMPLICIT} is not accepted and either {@code RETURN_VALUE} or
* {@code PARAMETERS} is required. This is the case for constructors with parameters
* and methods with parameters and return value.
*/
IMPLICIT,
/**
* Constraint applies to the return value of a method or a constructor.
*/
RETURN_VALUE,
/**
* Constraint applies to the parameters of a method or a constructor
*/
PARAMETERS
}</pre></div><p><span class="tck-testable">If a
<tt class="classname">ConstraintTarget</tt> is used in an illegal
situation, a <tt class="classname">ConstraintDeclarationException</tt> is
raised either at validation time or when the metadata is
requested.</span> Examples of illegal situations are:</p><div class="itemizedlist"><ul type="disc"><li><p class="tck-testable">using <tt class="literal">IMPLICIT</tt> in a
situation that cannot be inferred (see the JavaDoc for the
detailed rules),</p></li><li><p>using <tt class="literal">PARAMETERS</tt> on a constructor or
method that has no parameter,</p></li><li><p>using <tt class="literal">RETURN_VALUE</tt> on a method with no
return value,</p></li><li><p>using <tt class="literal">PARAMETERS</tt> or
<tt class="literal">RETURN_VALUE</tt> on a type - class or interface -
or on a field.</p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Question</h3><p>An alternative model would be to have
<tt class="classname">ConstraintTarget</tt> support
<tt class="literal">IMPLICIT</tt>, <tt class="literal">ANNOTATED_ELEMENT</tt>
and <tt class="literal">PARAMETERS</tt>. In this model,
<tt class="literal">ANNOTATED_ELEMENT</tt> can be used in all "natural
places" like types and fields and is synonym to
<tt class="literal">RETURN_VALUE</tt> for methods and constructors.</p></div><p>Constraint users are encouraged to set the explicit
<tt class="classname">ConstraintTarget</tt> target when using a constraint
supporting both on a method or constructor as it would improve
readability.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e755"></a>3.1.1.5. Constraint specific parameter</h4></div></div><div></div></div><p>The constraint annotation definitions may define additional
elements to parameterize the constraint. For example, a constraint
that validates the length of a string can use an annotation element
named <tt class="literal">length</tt> to specify the maximum length at the
time the constraint is declared.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e763"></a>3.1.2. Examples</h3></div></div><div></div></div><div class="example"><a name="example-definition-notnull"></a><p class="title"><b>Example 3.3. Simple constraint definition</b></p><pre class="programlisting">package com.acme.constraint;
/**
* Mark a String as representing a well formed order number
*/
@Documented
@Constraint(validatedBy = OrderNumberValidator.class)
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
public @interface OrderNumber {
String message() default "{com.acme.constraint.OrderNumber.message}";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}</pre></div><p><a href="#example-definition-notnull" title="Example 3.3. Simple constraint definition">Example 3.3, “Simple constraint definition”</a> marks a String as a
well-formed order number. The constraint validator is implemented by
<tt class="classname">OrderNumberValidator</tt>.</p><div class="added"><div class="example"><a name="example-definition-crossparameter"></a><p class="title"><b>Example 3.4. Simple cross-parameter constraint definition</b></p><pre class="programlisting">package com.acme.constraint;
/**
* Cross-parameter constraint ensuring that two date parameters
* of a method are in the correct order.
*/
@Documented
@CrossParameterConstraint(validatedBy = DateParametersConsistentValidator.class)
@Target({ METHOD, CONSTRUCTOR, ANNOTATION_TYPE })
@Retention(RUNTIME)
public @interface DateParametersConsistent {
String message() default "{com.acme.constraint.DateParametersConsistent.message}";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}</pre></div></div><div class="added"><p><a href="#example-definition-crossparameter" title="Example 3.4. Simple cross-parameter constraint definition">Example 3.4, “Simple cross-parameter constraint definition”</a> shows a cross-parameter
constraint which ensures that two date parameters of a method are in the
correct order. The constraint validator is implemented by
<tt class="classname">DateParametersConsistentValidator</tt>.</p></div><div class="added"><div class="example"><a name="example-definition-genericandcrossparameter"></a><p class="title"><b>Example 3.5. Constraint that is both generic and cross parameter</b></p><pre class="programlisting">package com.acme.constraint;
/**
* EL expression to be validated.
* This constraint accepts any type and can validate both the
* annotated type or apply restrictions across parameters.
*/
@Documented
@Constraint(validatedBy=ELAssertValidator.class)
@CrossParameterConstraint(validatedBy=ELAssertValidator.class)
@Target({ METHOD, CONSTRUCTOR, ANNOTATION_TYPE, FIELD })
@Retention(RUNTIME)
public @interface ELAssert {
String message() default "{com.acme.constraint.DateParametersConsistent.message}";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
ConstraintTarget validationAppliesTo() default ConstraintTarget.IMPLICIT;
String expression;
}</pre><pre class="programlisting">@ELAssert(expression="param[1]==param[2]", validationAppliesTo=ConstraintType.PARAMETERS)
public User createUser(String email, String password, String repreatPassword) { ... }</pre></div></div><div class="added"><p><a href="#example-definition-genericandcrossparameter" title="Example 3.5. Constraint that is both generic and cross parameter">Example 3.5, “Constraint that is both generic and cross parameter”</a> shows a
constraint that can be applied both on the annotated element and across
parameters of a method or a constructor. Note in this case the presence
of <tt class="methodname">validationAppliesTo</tt>.</p></div><div class="example"><a name="example-definition-length"></a><p class="title"><b>Example 3.6. Constraint definition with default parameter</b></p><pre class="programlisting">package com.acme.constraint;
/**
* A frequency in Hz as audible to human ear.
* Adjustable to the age of the person.
* Accept Numbers.
*/
@Documented
@Constraint(validatedBy = AudibleValidator.class)
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
public @interface Audible {
Age age() default Age.YOUNG;
String message() default "{com.acme.constraint.Audible.message}";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
public enum Age {
YOUNG,
WONDERING
OLD
}
}</pre></div><p><a href="#example-definition-length" title="Example 3.6. Constraint definition with default parameter">Example 3.6, “Constraint definition with default parameter”</a> ensures that a given
frequency is within the scope of human ears. The constraint definition
includes an optional parameter that may be specified when the constraint
is applied.</p><div class="example"><a name="example-definition-mandatory"></a><p class="title"><b>Example 3.7. Constraint definition with mandatory parameter</b></p><pre class="programlisting">package com.acme.constraint;
/**
* Defines the list of values accepted
* Accepts int or Integer objects
*/
@Documented
@Constraint(validatedBy = DiscreteListOfIntegerValidator.class)
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
public @interface Acceptable {
int[] value();
String message() default "{com.acme.constraint.Acceptable.message}";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}</pre></div><p><a href="#example-definition-mandatory" title="Example 3.7. Constraint definition with mandatory parameter">Example 3.7, “Constraint definition with mandatory parameter”</a> defines a list of
acceptable values expressed as an array: the
<tt class="methodname">value</tt> property must be specified when the
constraint is applied.</p><div class="added"><div class="example"><a name="example-definition-illegal"></a><p class="title"><b>Example 3.8. Illegal constraint definition</b></p><pre class="programlisting">package com.acme.constraint;
/**
* Cross-parameter constraint ensuring that two date parameters
* of a method are in the correct order.
*/
@Documented
@Constraint(validatedBy = DateParametersConsistentValidator.class)
@CrossParameterConstraint(validatedBy = AnotherDateParametersConsistentValidator.class)
@Target({ METHOD, CONSTRUCTOR, ANNOTATION_TYPE })
@Retention(RUNTIME)
public @interface DateParametersConsistent {
String message() default "{com.acme.constraint.DateParametersConsistent.message}";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}</pre></div></div><div class="added"><p><a href="#example-definition-illegal" title="Example 3.8. Illegal constraint definition">Example 3.8, “Illegal constraint definition”</a>
shows an illegal constraint definition ; an annotation may either be a
constraint annotation or a cross-parameter annotation but not
both.</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="constraintsdefinitionimplementation-multipleconstraints"></a>3.2. Applying multiple constraints of the same type</h2></div></div><div></div></div><p>It is often useful to declare the same constraint more than once to
the same target, with different properties. A common example is the
<tt class="literal">@Pattern</tt> constraint, which validates that its target
matches a specified regular expression. Other constraints have this
requirement as well. The same constraint type can belong to different
groups and have specific error messages depending on the targeted
group.</p><p>To support this requirement, <span class="tck-testable">the bean
validation provider treats regular annotations (annotations not annotated
by <tt class="classname">@Constraint</tt>) whose <tt class="literal">value</tt>
element has a return type of an array of constraint annotations in a
special way. Each element in the <tt class="literal">value</tt> array are
processed by the Bean Validation implementation as regular constraint
annotations.</span> This means that each constraint specified in the
<tt class="literal">value</tt> element is applied to the target. The annotation
must have retention <tt class="literal">RUNTIME</tt> and can be applied on a
type, field, property or another annotation. It is recommended to use the
same set of targets as the initial constraint.</p><p>Note to constraint designers: each constraint annotation should be
coupled with its corresponding multi-valued annotation. The specification
recommends, though does not mandate, the definition of an inner annotation
named <tt class="classname">List</tt>.</p><div class="example"><a name="d0e861"></a><p class="title"><b>Example 3.9. Multi-valued constraint definition</b></p><pre class="programlisting">/**
* Validate a zipcode for a given country
* The only supported type is String
*/
@Documented
@Constraint(validatedBy = ZipCodeValidator.class)
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
public @interface ZipCode {
String countryCode();
String message() default "{com.acme.constraint.ZipCode.message}";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
/**
* Defines several @ZipCode annotations on the same element
* @see (@link ZipCode}
*/
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@Documented
@interface List {
ZipCode[] value();
}
}</pre></div><div class="example"><a name="d0e866"></a><p class="title"><b>Example 3.10. Multi-valued constraint declaration</b></p><pre class="programlisting">public class Address {
@ZipCode.List( {
@ZipCode(countryCode="fr", groups=Default.class
message = "zip code is not valid"),
@ZipCode(countryCode="fr", groups=SuperUser.class
message = "zip code invalid. Requires overriding before saving.")
} )
private String zipcode;
}</pre></div><p>In this example, both constraints apply to the
<tt class="methodname">zipcode</tt> field but with different groups and with
different error messages.</p><p>Using two different multi-constraint annotations for the same
underlying constraint type on the same target (i.e. class or property) is
not considered portable and is discouraged.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="constraintsdefinitionimplementation-constraintcomposition"></a>3.3. Constraint composition</h2></div></div><div></div></div><p>This specification allows you to compose constraints to create
higher level constraints.</p><p>Constraint composition is useful in several ways:</p><div class="itemizedlist"><ul type="disc"><li><p>Avoid duplication and facilitate reuse of more primitive
constraints.</p></li><li><p>Expose primitive constraints as part of a composed constraint in
the metadata API and enhance tool awareness.</p></li></ul></div><p>Composition is done by annotating a constraint annotation with the
composing constraint annotations.</p><div class="example"><a name="d0e894"></a><p class="title"><b>Example 3.11. Composition is done by annotating the composed constraint</b></p><pre class="programlisting">@Pattern(regexp="[0-9]*")
@Size(min=5, max=5)
@Constraint(validatedBy = FrenchZipcodeValidator.class)
@Documented
@Target({ANNOTATION_TYPE, METHOD, FIELD, CONSTRUCTOR, PARAMETER})
@Retention(RUNTIME)
public @interface FrenchZipcode {
String message() default "Wrong zipcode";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@Documented
@interface List {
FrenchZipcode[] value();
}
}</pre></div><p>Annotating an element with <tt class="classname">@FrenchZipcode</tt>
(the composed annotation) is equivalent to annotating it with
<tt class="classname">@Pattern(regexp="[0-9]*")</tt>, <tt class="classname">@Size(min=5,
max=5)</tt> (the composing annotations) and
<tt class="classname">@FrenchZipcode</tt>. <span class="tck-testable tck-needs-update">More formally, each constraint
annotation hosted on a constraint annotation is applied to the target
element and this is done recursively.</span> <span class="tck-testable">Note that the main annotation and its constraint
validation implementation is also applied.</span> <span class="tck-testable">By default, each failing constraint generates an error
report.</span> <span class="tck-testable">Groups from the main
constraint annotation are inherited by the composing annotations.</span>
<span class="tck-testable">Any <tt class="methodname">groups</tt> definition
on a composing annotation is ignored. </span><span class="tck-testable">Payload from the main constraint annotation is
inherited by the composing annotations.</span> <span class="tck-testable">Any <tt class="methodname">payload</tt> definition on a
composing annotation is ignored. </span><span class="added"><span class="tck-testable">the constraint target from the main constraint
annotation is inherited by the composing annotations.</span></span><span class="added"><span class="tck-testable"> Any
<tt class="methodname">validationAppliesTo</tt> definition on a composing
annotation is ignored.</span></span></p><p><span class="tck-testable">The <span class="deleted"><span>property</span></span> type upon which composed
constraint is placed must be compatible with all constraints (composing
and composed).</span> A constraint designer should ensure that such a
type exists and list in the JavaDoc all the compatible types.</p><div class="added"><p>Both composed and composing constraints should
share the same constraint type. In particular, it is not legal to mix a
pure generic <tt class="classname">@Constraint</tt> and a pure cross-parameter
<tt class="classname">@CrossParameterConstraint</tt>.</p></div><p>It is possible to ensure that composing annotations do not raise
individual error reports. In this scenario, if one or more composing
annotations are invalid, the main constraint is automatically considered
invalid and the corresponding error report is generated. To mark a
constraint as raising a single constraint error report if either the
composed or one of the composing constraints fail, use the
<tt class="classname">@ReportAsSingleViolation</tt> annotation.</p><div class="example"><a name="d0e965"></a><p class="title"><b>Example 3.12. If any of the composing constraints fail, the error report
corresponding to @FrenchZipcode is raised and none other.</b></p><pre class="programlisting">@Pattern(regexp="[0-9]*")
@Size(min=5, max=5)
@ReportAsSingleViolation
@Constraint(validatedBy = FrenchZipcodeValidator.class)
@Documented
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
public @interface FrenchZipcode {
String message() default "Wrong zipcode";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@Documented
@interface List {
FrenchZipcode[] value();
}
}</pre></div><p>The definition of <tt class="classname">@ReportAsSingleViolation</tt> is
as follows.</p><div class="changed"><pre class="programlisting">/**
* A constraint annotation hosting this annotation will return the
* composed annotation error report if any of the composing annotations fail.
* The error reports of each individual composing constraint are ignored.
*
* <p>
* Note: Evaluation of composed constraints stops on the first validation
* error in case the composing constraint is annotated with
* {@code @ReportAsSingleViolation}.
* </p>
*
* @author Emmanuel Bernard
*/
@Target({ ANNOTATION_TYPE })
@Retention(RUNTIME)
public @interface ReportAsSingleViolation {
}</pre></div><div class="changed"><p class="tck-testable">More specifically, if a
composed constraint is marked as
<tt class="classname">@ReportAsSingleViolation</tt>, the evaluation of the
composing constraints stops at the first failing constraint and the error
report corresponding to the composed constraint is generated and
returned.</p></div><p class="tck-testable">Composing annotations can define the value of
<tt class="literal">message</tt> and custom attributes (excluding
<tt class="methodname">groups</tt> and <tt class="methodname">payload</tt>) but
these are fixed in the composed constraint definition.</p><div class="example"><a name="d0e993"></a><p class="title"><b>Example 3.13. Composing annotations can use attributes. They are fixed for a
given main annotation. All @FrenchZipcode constraints have a @Size
restricted to 5.</b></p><pre class="programlisting">@Pattern(regexp="[0-9]*")
@Size(min=5, max=5)
@Constraint(validatedBy = FrenchZipcodeValidator.class)
@Documented
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
public @interface FrenchZipcode {
String message() default "Wrong zipcode";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@Documented
@interface List {
FrenchZipcode[] value();
}
}</pre></div><p class="tck-testable">It is possible to override attributes and
messages defined on a composing annotation. An attribute from the main
annotation is used to override one or more attributes of the composing
annotations. Such an attribute is annotated with the
<tt class="classname">@OverridesAttribute</tt> annotation or its multivalued
equivalent <tt class="classname">@OverridesAttribute.List</tt>.</p><div class="example"><a name="example-composing-overridden"></a><p class="title"><b>Example 3.14. Attributes from composing annotations can be overridden by
attributes from the composed annotation.</b></p><pre class="programlisting">@Pattern(regexp="[0-9]*")
@Size
@Constraint(validatedBy = FrenchZipcodeValidator.class)
@Documented
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
public @interface FrenchZipcode {
String message() default "Wrong zipcode";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
@OverridesAttribute.List( {
@OverridesAttribute(constraint=Size.class, name="min"),
@OverridesAttribute(constraint=Size.class, name="max") } )
int size() default 5;
@OverridesAttribute(constraint=Size.class, name="message")
String sizeMessage() default "{com.acme.constraint.FrenchZipcode.zipcode.size}";
@OverridesAttribute(constraint=Pattern.class, name="message")
String numberMessage() default "{com.acme.constraint.FrenchZipcode.number.size}";
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@Documented
@interface List {
FrenchZipcode[] value();
}
}</pre></div><p>The value of the composed constraint attribute annotated with
<tt class="classname">@OverridesAttribute</tt>
(<tt class="methodname">@FrenchZipcode.sizeMessage</tt>) is applied to the
composing constraint attribute named after
<tt class="methodname">OverridesAttribute.name</tt> and hosted on the
composing constraint of type
<tt class="methodname">OverridesAttribute.constraint</tt>
(<tt class="methodname">@Size.message</tt>). Similarly,
<tt class="classname">@FrenchZipcode.numberMessage</tt> value is mapped to
<tt class="classname">@Pattern.message</tt>.</p><p>If left undefined, the default value for
<tt class="methodname">@OverridesAttribute.name</tt> is the name of the
composed constraint attribute hosting the
<tt class="classname">@OverridesAttribute</tt> annotation.</p><p class="tck-testable">The types of the overridden and overriding
attributes must be identical.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><span class="tck-testable">A composing constraint can itself be a
composed constraint. In this case, attribute values are overridden
recursively according to the described rules.</span> Note however,
that a forwarding rule (as defined by
<tt class="classname">@OverridesAttribute</tt>) is only applied to the
direct composing constraints.</p></div><p>Using <a href="#example-composing-overridden" title="Example 3.14. Attributes from composing annotations can be overridden by
 attributes from the composed annotation.">Example 3.14, “Attributes from composing annotations can be overridden by
attributes from the composed annotation.”</a>,</p><pre class="programlisting">@FrenchZipcode(size=9, sizeMessage="Zipcode should be of size {max}")</pre><p>is equivalent to</p><pre class="programlisting">@FrenchZipcode</pre><p>if <tt class="classname">@FrenchZipcode</tt> is defined as</p><pre class="programlisting">@Pattern(regexp="[0-9]*")
@Size(min=9, max=9, message="Zipcode should be of size {max}")
@Constraint(validatedBy = FrenchZipcodeValidator.class)
@Documented
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
public @interface FrenchZipcode {
String message() default "Wrong zipcode";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@Documented
@interface List {
FrenchZipcode[] value();
}
}</pre><p><span class="tck-testable">If a constraint is used more than once
as a composing constraint, the multi value constraints model as described
in <a href="#constraintsdefinitionimplementation-multipleconstraints" title="3.2. Applying multiple constraints of the same type">Section 3.2, “Applying multiple constraints of the same type”</a> is
used.</span> <span class="tck-testable">To select a specific composing
constraint, <tt class="methodname">OverridesAttribute.constraintIndex</tt> is
used. It represents the constraint index in the
<tt class="methodname">value</tt> array.</span> <span class="tck-testable">If <tt class="literal">index</tt> is undefined, the single
constraint declaration is targeted.</span></p><div class="example"><a name="d0e1089"></a><p class="title"><b>Example 3.15. Use of constraintIndex in @OverridesAttribute</b></p><pre class="programlisting">@Pattern.List( {
@Pattern(regexp="[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}"), //email
@Pattern(regexp=".*?emmanuel.*?") //emmanuel
} )
@Constraint(validatedBy={})
@Documented
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
public @interface EmmanuelsEmail {
String message() default "Not emmanuel's email";
@OverridesAttribute(constraint=Pattern.class, name="message", constraintIndex=0)
String emailMessage() default "Not an email";
@OverridesAttribute(constraint=Pattern.class, name="message", constraintIndex=1)
String emmanuelMessage() default "Not Emmanuel";
Class<?>[] groups() default {};
Class<? extends Payload>[] y() default {};
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@Documented
@interface List {
EmmanuelsEmail[] value();
}
}</pre></div><p><tt class="classname">@OverridesAttribute</tt> definition is as
follows:</p><pre class="programlisting">/**
* Mark an attribute as overriding the attribute of a composing constraint.
* Both attributes must share the same type.
*
* @author Emmanuel Bernard
*/
@Retention(RUNTIME)
@Target({ METHOD })
public @interface OverridesAttribute {
/**
* @return Constraint type the attribute is overriding
*/
Class<? extends Annotation> constraint();
/**
* Name of the Constraint attribute overridden.
* Defaults to the name of the attribute hosting <code>@OverridesAttribute</code>.
*
* @return name of constraint attribute overridden.
*/
String name();
/**
* The index of the targeted constraint declaration when using
* multiple constraints of the same type.
* The index represents the index of the constraint in the value() array.
*
* By default, no index is defined and the single constraint declaration
* is targeted
*
* @return constraint declaration index if multivalued annotation is used
*/
int constraintIndex() default -1;
/**
* Defines several @OverridesAttribute annotations on the same element
* @see javax.validation.OverridesAttribute
*/
@Documented
@Target({ METHOD })
@Retention(RUNTIME)
public @interface List {
OverridesAttribute[] value();
}
}</pre><p>The following elements uniquely identify an overridden constraint
attribute:</p><div class="itemizedlist"><ul type="disc"><li><p><tt class="methodname">OverridesAttribute.constraint</tt></p></li><li><p><tt class="methodname">OverridesAttribute.name</tt></p></li><li><p><tt class="methodname">OverridesAttribute.constraintIndex</tt></p></li></ul></div><p class="tck-testable tck-needs-update">If the composition is invalid,
e.g. </p><div class="itemizedlist"><ul type="disc"><li><p>infinitely recursive composition</p></li><li><p>wrong attribute overriding</p></li><li><p>a single attribute mapped to more than one source
attribute</p></li><li><div class="added"><p>A composing and composed constraint
marked as different constraint types (i.e., generic with
<tt class="classname">@Constraint</tt> and cross-parameter with
<tt class="classname">@CrossParameterConstraint</tt>)</p></div></li><li><p>etc.</p></li></ul></div><p class="tck-testable tck-needs-update">a <tt class="classname">ConstraintDefinitionException</tt> is
raised either at validation time or when the metadata is requested.</p><p>Constraint designers are encouraged to make use of composition
(recursively or not) based on the built-in constraints defined by the
specification. The composing constraints are exposed through the Bean
Validation metadata API (<a href="#constraintmetadata-constraintdescriptor" title="6.10. ConstraintDescriptor">Section 6.10, “ConstraintDescriptor”</a>). This metadata is
particularly useful for third-party metadata consumers like persistence
frameworks generating database schemas (such as Java Persistence) or
presentation frameworks.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="constraintsdefinitionimplementation-validationimplementation"></a>3.4. Constraint validation implementation</h2></div></div><div></div></div><p><span class="tck-testable">A constraint validation implementation
performs the validation of a given constraint annotation for a given
type.</span> <span class="tck-testable tck-needs-update">The
implementation classes are specified by the <tt class="literal">validatedBy</tt>
element of the <tt class="classname">@Constraint</tt> <span class="added"><span>respectively
<tt class="classname">@CrossParameterConstraint</tt></span></span> annotation that
decorates the constraint definition.</span> <span class="tck-not-testable">The constraint validation implementation
implements the <tt class="classname">ConstraintValidator</tt>
interface.</span></p><pre class="programlisting">/**
* Defines the logic to validate a given constraint A
* for a given object type T.
* Implementations must comply to the following restriction:
* <ul>
* <li>T must resolve to a non parameterized type</li>
* <li>or generic parameters of T must be unbounded
* wildcard types</li>
* </ul>
*
* @author Emmanuel Bernard
* @author Hardy Ferentschik
*/
public interface ConstraintValidator<A extends Annotation, T> {
/**
* Initialize the validator in preparation for isValid calls.
* The constraint annotation for a given constraint declaration
* is passed.
* <p/>
* This method is guaranteed to be called before any use of this instance for
* validation.
*
* @param constraintAnnotation annotation instance for a given constraint declaration
*/
void initialize(A constraintAnnotation);
/**
* Implement the validation logic.
* The state of <code>value</code> must not be altered.
*
* This method can be accessed concurrently, thread-safety must be ensured
* by the implementation.
*
* @param value object to validate
* @param context context in which the constraint is evaluated
*
* @return false if <code>value</code> does not pass the constraint
*/
boolean isValid(T value, ConstraintValidatorContext context);
}</pre><p class="tck-not-testable">Some restrictions apply on the generic type
<tt class="classname">T</tt> (used in the <tt class="methodname">isValid</tt>
method). <tt class="classname">T</tt> must </p><div class="itemizedlist"><ul type="disc"><li><p>resolve to a non parameterized type (i.e. because the type is
not using generics or because the raw type is used instead of the
generic version)</p></li><li><p>or generic parameters of <tt class="classname">T</tt> must be
unbounded wildcard types (i.e. <tt class="literal"><?></tt>).</p></li></ul></div><div class="added"><p class="tck-testable">If <tt class="classname">A</tt>
is a cross-parameter constraint annotation type, <tt class="classname">T</tt>
must resolve to <tt class="classname">Object[]</tt> in order to have the array
of parameter values passed to the <tt class="methodname">isValid()</tt>
method.</p></div><p><a href="#example-constraintsdefinitionimplementation-validationimplementation-validdef" title="Example 3.16. Valid ConstraintValidator definitions">Example 3.16, “Valid ConstraintValidator definitions”</a>
shows some examples of valid definitions.</p><div class="changed"><div class="example"><a name="example-constraintsdefinitionimplementation-validationimplementation-validdef"></a><p class="title"><b>Example 3.16. Valid ConstraintValidator definitions</b></p><pre class="programlisting">//String is not making use of generics
public class SizeValidatorForString implements<Size, String> {...}
//Collection uses generics but the raw type is used
public class SizeValidatorForCollection implements<Size, Collection> {...}
//Collection uses generics and unbounded windcard type
public class SizeValidatorForCollection implements<Size, Collection<?>> {...}
//Validator for cross-parameter constraint
public class DateParametersConsistentValidator implements<DateParametersConsistent, Object[]> {...}</pre></div></div><p>And some invalid definitions in <a href="#example-constraintsdefinitionimplementation-validationimplementation-invaliddef" title="Example 3.17. Invalid ConstraintValidator definitions">Example 3.17, “Invalid ConstraintValidator definitions”</a>.</p><div class="example"><a name="example-constraintsdefinitionimplementation-validationimplementation-invaliddef"></a><p class="title"><b>Example 3.17. Invalid ConstraintValidator definitions</b></p><pre class="programlisting">//parameterized type
public class SizeValidatorForString implements<Size, Collection<String>> {...}
//parameterized type using bounded wildcard
public class SizeValidatorForCollection implements<Size, Collection<? extends Address>> {...}</pre></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This restriction is not a theoretical limitation and a future
version of the specification will likely allow it.</p></div><div class="changed"><p>The life cycle of a constraint validation
implementation instance is undefined. Bean Validation providers are
allowed to cache <tt class="classname">ConstraintValidator</tt> instances
retrieved from the
<tt class="classname">ConstraintValidatorFactory</tt>.</p></div><p class="tck-testable">The <tt class="methodname">initialize</tt> method
is called by the Bean validation provider prior to any use of the
constraint implementation.</p><p><span class="tck-testable">The <tt class="methodname">isValid</tt>
method is evaluated by the Bean Validation provider each time a given
value is validated.</span> <span class="tck-not-testable">It returns
<tt class="literal">false</tt> if the value is not valid,
<tt class="literal">true</tt> otherwise.</span> <span class="tck-not-testable"><tt class="literal">isValid</tt> implementations must be
thread-safe.</span></p><p><span class="tck-testable">If the property is of an unanticipated
type, an <tt class="literal">UnexpectedTypeException</tt> is raised.</span>
<tt class="classname">ConstraintValidator</tt> implementations raise this
exception themselves if they receive an unsupported type. However,
constraint designers are encouraged to make use of specialized
<tt class="classname">ConstraintValidator</tt> implementations and delegate
the type resolution to the Bean Validation provider (see the type matching
algorithm described in <a href="#typevalidatorresolution" title="4.6.4. ConstraintValidator resolution algorithm">Section 4.6.4, “ConstraintValidator resolution algorithm”</a>).</p><p class="tck-testable">If an exception occurs either in the
<tt class="classname">initialize</tt> or <tt class="classname">isValid</tt>
method, the runtime exception is wrapped into a
<tt class="classname">ValidationException</tt> by the Bean Validation
engine.</p><p class="tck-not-testable">The constraint validation implementation is
not allowed to change the state of the value passed to
<tt class="methodname">isValid</tt>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>While not mandatory, it is considered a good practice to split the
core constraint validation from the not null constraint validation (for
example, an <tt class="classname">@Email</tt> constraint will return true on
a null object, i.e. will not take care of the