| 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 |
|