Debian Codegraph @

documentation/src/main/asciidoc/ch12.asciidoc

raw
1 [[validator-annotation-processor]]
2 == Annotation Processor
3
4 Have you ever caught yourself by unintentionally doing things like
5
6 * specifying constraint annotations at unsupported data types (e.g. by annotating a String with `@Past`)
7 * annotating the setter of a JavaBeans property (instead of the getter method)
8 * annotating static fields/methods with constraint annotations (which is not supported)?
9
10 Then the Hibernate Validator Annotation Processor is the right thing for you. It helps preventing
11 such mistakes by plugging into the build process and raising compilation errors whenever constraint
12 annotations are incorrectly used.
13
14 [TIP]
15 ====
16 You can find the Hibernate Validator Annotation Processor as part of the distribution bundle on
17 http://sourceforge.net/projects/hibernate/files/hibernate-validator[Sourceforge] or in the
18 usual Maven repositories such as Maven Central under the GAV `org.hibernate:hibernate-validator-
19 annotation-processor:{hvVersion}`.
20 ====
21
22 [[validator-annotationprocessor-prerequisites]]
23 === Prerequisites
24
25 The Hibernate Validator Annotation Processor is based on the "Pluggable Annotation Processing API"
26 as defined by http://jcp.org/en/jsr/detail?id=269[JSR 269] which is part of the Java
27 Platform since Java 6.
28
29 [[validator-annotationprocessor-features]]
30 === Features
31
32 As of Hibernate Validator {hvVersion} the Hibernate Validator Annotation Processor checks that:
33
34 * constraint annotations are allowed for the type of the annotated element
35 * only non-static fields or methods are annotated with constraint annotations
36 * only non-primitive fields or methods are annotated with `@Valid`
37 * only such methods are annotated with constraint annotations which are valid JavaBeans
38 getter methods (optionally, see below)
39 * only such annotation types are annotated with constraint annotations which are constraint
40 annotations themselves
41 * definition of dynamic default group sequence with @GroupSequenceProvider is valid
42
43 [[validator-annotationprocessor-options]]
44 === Options
45
46 The behavior of the Hibernate Validator Annotation Processor can be controlled using the
47 http://java.sun.com/javase/6/docs/technotes/tools/windows/javac.html#options[processor options]
48 listed in table <<table_processor_options>>:
49
50 [[table_processor_options]]
51 .Hibernate Validator Annotation Processor options
52 [options="header"]
53 |===============
54 |Option|Explanation
55 |`diagnosticKind`|Controls how constraint problems are reported. Must be the
56 string representation of one of the values from the enum `javax.tools.Diagnostic.Kind`,
57 e.g. `WARNING`. A value of `ERROR` will cause compilation to halt whenever the AP detects
58 a constraint problem. Defaults to `ERROR`.
59 |`methodConstraintsSupported`|Controls whether constraints are allowed at methods of any
60 kind. Must be set to `true` when working with method level constraints as supported by
61 Hibernate Validator. Can be set to `false` to allow constraints only at
62 JavaBeans getter methods as defined by the Bean Validation API. Defaults to `true`.
63 |`verbose`|Controls whether detailed processing information shall be
64 displayed or not, useful for debugging purposes. Must be either
65 `true` or `false`. Defaults to `false`.
66
67 |===============
68
69
70 [[validator-annotationprocessor-usage]]
71 === Using the Annotation Processor
72
73 This section shows in detail how to integrate the Hibernate Validator Annotation Processor into
74 command line builds (javac, Ant, Maven) as well as IDE-based builds (Eclipse, IntelliJ IDEA,
75 NetBeans).
76
77 [[validator-annotationprocessor-commandline]]
78
79
80 ==== Command line builds
81
82 [[validator-annotationprocessor-javac]]
83 ===== javac
84
85 When compiling on the command line using
86 http://java.sun.com/javase/6/docs/technotes/guides/javac/index.html[javac], specify the JAR
87 _hibernate-validator-annotation-processor-{hvVersion}.jar_ using the "processorpath" option as shown in
88 the following listing. The processor will be detected automatically by the compiler and invoked
89 during compilation.
90
91 .Using the annotation processor with javac
92 ====
93 [subs="verbatim,attributes"]
94 ----
95 javac src/main/java/org/hibernate/validator/ap/demo/Car.java \
96 -cp /path/to/validation-api-{bvVersion}.jar \
97 -processorpath /path/to/hibernate-validator-annotation-processor-{hvVersion}.jar
98 ----
99 ====
100
101 [[validator-annotationprocessor-ant]]
102 ===== Apache Ant
103
104 Similar to directly working with javac, the annotation processor can be added as as compiler
105 argument when invoking the http://ant.apache.org/manual/CoreTasks/javac.html[javac task]
106 for http://ant.apache.org/[Apache Ant]:
107
108 .Using the annotation processor with An
109 ====
110 [source, XML]
111 [subs="verbatim,attributes"]
112 ----
113 <javac srcdir="src/main"
114 destdir="build/classes"
115 classpath="/path/to/validation-api-{bvVersion}.jar">
116 <compilerarg value="-processorpath" />
117 <compilerarg value="/path/to/hibernate-validator-annotation-processor-{hvVersion}.jar"/>
118 </javac>
119 ----
120 ====
121
122 ===== Maven
123
124 There are several options for integrating the annotation processor with
125 http://maven.apache.org/[Apache Maven]. Generally it is sufficient to add the Hibernate
126 Validator Annotation Processor as dependency to your project:
127
128 .Adding the HV Annotation Processor as dependency
129 ====
130 [source, XML]
131 [subs="verbatim,attributes"]
132 ----
133 ...
134 <dependency>
135 <groupId>org.hibernate</groupId>
136 <artifactId>hibernate-validator-annotation-processor</artifactId>
137 <version>{hvVersion}</version>
138 </dependency>
139 ...
140 ----
141 ====
142
143 The processor will then be executed automatically by the compiler. This basically works, but comes
144 with the disadavantage that in some cases messages from the annotation processor are not displayed
145 (see http://jira.codehaus.org/browse/MCOMPILER-66[MCOMPILER-66]).
146
147 Another option is using the http://code.google.com/p/maven-annotation-plugin[Maven Annotation Plugin].
148 To work with this plugin, disable the standard annotation processing performed
149 by the compiler plugin and configure the annotation plugin by specifying an execution and adding the
150 Hibernate Validator Annotation Processor as plugin dependency (that way the processor is not visible
151 on the project's actual classpath):
152
153 .Configuring the Maven Annotation Plugin
154 ====
155 [source, XML]
156 [subs="verbatim,attributes"]
157 ----
158 ...
159 <plugin>
160 <artifactId>maven-compiler-plugin</artifactId>
161 <configuration>
162 <source>1.6</source>
163 <target>1.6</target>
164 <compilerArgument>-proc:none</compilerArgument>
165 </configuration>
166 </plugin>
167 <plugin>
168 <groupId>org.bsc.maven</groupId>
169 <artifactId>maven-processor-plugin</artifactId>
170 <version>2.2.1</version>
171 <executions>
172 <execution>
173 <id>process</id>
174 <goals>
175 <goal>process</goal>
176 </goals>
177 <phase>process-sources</phase>
178 </execution>
179 </executions>
180 <dependencies>
181 <dependency>
182 <groupId>org.hibernate</groupId>
183 <artifactId>hibernate-validator-annotation-processor</artifactId>
184 <version>{hvVersion}</version>
185 </dependency>
186 </dependencies>
187 </plugin>
188 ...
189 ----
190 ====
191
192 [[validator-annotationprocessor-ide]]
193 ==== IDE builds
194
195 ===== Eclipse
196
197 Do the following to use the annotation processor within the http://www.eclipse.org/[Eclipse] IDE:
198
199 * Right-click your project, choose "Properties"
200 * Go to "Java Compiler" and make sure, that "Compiler compliance level" is set to "1.6".
201 Otherwise the processor won't be activated
202 * Go to "Java Compiler - Annotation Processing" and choose "Enable annotation processing"
203 * Go to "Java Compiler - Annotation Processing - Factory Path" and add the JAR
204 hibernate-validator-annotation-processor-{hvVersion}.jar
205 * Confirm the workspace rebuild
206
207 You now should see any annotation problems as regular error markers within the editor and in the
208 "Problem" view:
209
210 image::annotation_processor_eclipse.png[]
211
212 [[validator-annotationprocessor-idea]]
213 ===== IntelliJ IDEA
214
215 The following steps must be followed to use the annotation processor within
216 http://www.jetbrains.com/idea/[IntelliJ IDEA] (version 9 and above):
217
218 * Go to "File", then "Settings",
219 * Expand the node "Compiler", then "Annotation Processors"
220 * Choose "Enable annotation processing" and enter the following as "Processor path":
221 /path/to/hibernate-validator-annotation-processor-{hvVersion}.jar
222 * Add the processor's fully qualified name org.hibernate.validator.ap.ConstraintValidationProcessor
223 to the "Annotation Processors" list
224 * If applicable add you module to the "Processed Modules" list
225
226 Rebuilding your project then should show any erronous constraint annotations:
227
228 image::annotation_processor_intellij.png[]
229
230 [[validator-annotationprocessor-netbeans]]
231 ===== NetBeans
232
233 Starting with version 6.9, also the http://www.netbeans.org/[NetBeans] IDE supports using
234 annotation processors within the IDE build. To do so, do the following:
235
236 * Right-click your project, choose "Properties"
237 * Go to "Libraries", tab "Processor", and add the JAR hibernate-validator-annotation-processor-{hvVersion}.jar
238 * Go to "Build - Compiling", select "Enable Annotation Processing" and "Enable Annotation Processing
239 in Editor". Add the annotation processor by specifying its fully qualified name
240 org.hibernate.validator.ap.ConstraintValidationProcessor
241
242 Any constraint annotation problems will then be marked directly within the editor:
243
244 image::annotation_processor_netbeans.png[]
245
246 [[validator-annotationprocessor-known-issues]]
247 === Known issues
248
249 The following known issues exist as of May 2010:
250
251 * https://hibernate.atlassian.net/browse/HV-308[HV-308]: Additional validators
252 registered for a constraint
253 http://docs.jboss.org/hibernate/stable/validator/reference/en-US/html_single/#chapter-xml-configuration[using XML] are
254 not evaluated by the annotation processor.
255
256 * Sometimes custom constraints can't be
257 https://hibernate.atlassian.net/browse/HV-293[properly evaluated] when
258 using the processor within Eclipse. Cleaning the project can help in these situations. This seems to
259 be an issue with the Eclipse JSR 269 API implementation, but further investigation is required here.
260
261 * When using the processor within Eclipse, the check of dynamic default group sequence definitions
262 doesn't work. After further investigation, it seems to be an issue with the Eclipse JSR 269 API
263 implementation.
264