[hibernate-commits] Hibernate SVN: r19373 - in validator/trunk/hibernate-validator/src/main/docbook/en-US: modules and 1 other directory.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Wed May 5 18:12:40 EDT 2010
Author: gunnar.morling
Date: 2010-05-05 18:12:39 -0400 (Wed, 05 May 2010)
New Revision: 19373
Added:
validator/trunk/hibernate-validator/src/main/docbook/en-US/images/annotation_processor_eclipse.png
validator/trunk/hibernate-validator/src/main/docbook/en-US/images/annotation_processor_netbeans.png
validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/annotationprocessor.xml
Log:
HV-298: initial version of the ref guide chapter on the AP. This is work in progress, the chapter is not yet referenced from the main doc.
Added: validator/trunk/hibernate-validator/src/main/docbook/en-US/images/annotation_processor_eclipse.png
===================================================================
(Binary files differ)
Property changes on: validator/trunk/hibernate-validator/src/main/docbook/en-US/images/annotation_processor_eclipse.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: validator/trunk/hibernate-validator/src/main/docbook/en-US/images/annotation_processor_netbeans.png
===================================================================
(Binary files differ)
Property changes on: validator/trunk/hibernate-validator/src/main/docbook/en-US/images/annotation_processor_netbeans.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/annotationprocessor.xml
===================================================================
--- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/annotationprocessor.xml (rev 0)
+++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/annotationprocessor.xml 2010-05-05 22:12:39 UTC (rev 19373)
@@ -0,0 +1,496 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- $Id$ -->
+<!--
+ ~ JBoss, Home of Professional Open Source
+ ~ Copyright 2009, Red Hat, Inc. and/or its affiliates, and individual contributors
+ ~ by the @authors tag. See the copyright.txt in the distribution for a
+ ~ full listing of individual contributors.
+ ~
+ ~ Licensed under the Apache License, Version 2.0 (the "License");
+ ~ you may not use this file except in compliance with the License.
+ ~ You may obtain a copy of the License at
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~ Unless required by applicable law or agreed to in writing, software
+ ~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~ See the License for the specific language governing permissions and
+ ~ limitations under the License.
+-->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter>
+ <title id="chapter-annotation-processor">The Hibernate Validation Annotation
+ Processor (EXPERIMENTAL)
+ </title>
+
+ <para>Have you ever caught yourself by unintentionally doing things
+ like
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>annotating Strings with @Min to specify a minimum length (instead
+ of using @Size)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>annotating the setter of a JavaBean property (instead of the
+ getter method)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>annotating static fields/methods with constraint annotations
+ (which is not supported)?
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Then the Hibernate Validator Annotation Processor is the right thing
+ for you. It helps in preventing such mistakes by plugging in into the build
+ process and raising compilation errors whenever constraint annotations are
+ incorrectly used.
+ </para>
+
+ <section>
+ <title>Prerequisites</title>
+
+ <para>The Hibernate Validator Annotation Processor is based on the
+ "Pluggable Annotation Processing API" as defined by<ulink
+ url="http://jcp.org/en/jsr/detail?id=269">JSR 269</ulink>.This API is part
+ of the Java Platform since Java 6. So be sure to use this or a later
+ version.
+ </para>
+
+ <para>TODO GM: add note on experimental state of the AP</para>
+ </section>
+
+ <section id="section-features-of-the-ap">
+ <title>Features</title>
+
+ <para>As of Hibernate Validator 4.1 the Hibernate Validator Annotation
+ Processor checks:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>whether constraint annotations are allowed for the type of the
+ annotated element
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>that for JavaBean properties the getter method is
+ annotated
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>that only non-static fields or properties are annotated with
+ constraint annotations
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>that only non-primitive fields or properties are annotated with
+ @Valid
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>that only such annotation types are annotated with constraint
+ annotations which are constraint annotations themselves
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Options</title>
+
+ <para>The behavior of the Hibernate Validator Annotation Processor can be
+ controlled using the
+ <ulink
+ url="http://java.sun.com/javase/6/docs/technotes/tools/windows/javac.html#options">processor
+ options
+ </ulink>
+ listed in table<xref
+ linkend="table_processor_options"/>:
+ </para>
+
+ <table id="table_processor_options">
+ <title>Hibernate Validator Annotation Processor options</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry align="center">Option</entry>
+
+ <entry align="center">Explanation</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>
+ <varname>diagnosticKind</varname>
+ </entry>
+
+ <entry>Controls how constraint problems are reported. Must be the
+ string representation of one of the values from the enum
+ <classname>javax.tools.Diagnostic.Kind</classname>, e.g.
+ <classname>WARNING</classname>. A value of
+ <classname>ERROR</classname>
+ will cause compilation to halt
+ whenever the AP detects a constraint problem. Defaults to
+ ERROR.
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <varname>verbose</varname>
+ </entry>
+
+ <entry>TODO GM: NOT YET IMPLEMENTED. Controls whether detailed
+ processing information shall be displayed or not, useful for
+ debugging purposes. Must be either
+ <varname>true</varname>
+ or
+ <varname>false</varname>. Defaults to
+ <varname>false</varname>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>Using the Annotation Processor</title>
+
+ <para>This section shows in detail how to integrate the Hibernate
+ Validator Annotation Processor into command line builds (javac, Ant,
+ Maven) as well as IDE-based builds (Eclipse, IntelliJ IDEA,
+ NetBeans).
+ </para>
+
+ <section>
+ <title>javac</title>
+
+ <para>When compiling on the command line using<ulink
+ url="http://java.sun.com/javase/6/docs/technotes/guides/javac/index.html">javac</ulink>,
+ specify the following JARs using the "processorpath" option:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>validation-api-1.0.0.GA.jar</para>
+ </listitem>
+
+ <listitem>
+ <para>hibernate-validator-annotation-processor-4.1.0.GA.jar</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following example shows the compilation of one class. The
+ processor will be detected automatically by the compiler and invoked
+ during compilation.
+ </para>
+
+ <example>
+ <title>Using the annotation processor with javac</title>
+
+ <programlisting>javac src/main/java/org/hibernate/validator/ap/demo/Car.java
+ -cp /path/to/validation-api-1.0.0.GA.jar
+ -processorpath
+ /path/to/validation-api-1.0.0.GA.jar:/path/to/hibernate-validator-annotation-processor-4.1.0.GA.jar
+ </programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>Apache Ant</title>
+
+ <para>Similar to directly working with javac, the annotation processor
+ can be added as as compiler argument when invoking the
+ <ulink
+ url="http://ant.apache.org/manual/CoreTasks/javac.html">javac
+ task
+ </ulink>
+ for<ulink url="http://ant.apache.org/">Apache
+ Ant</ulink>:
+ </para>
+
+ <example>
+ <title>Using the annotation processor with Ant</title>
+
+ <programlisting><javac
+ srcdir="src/main"
+ destdir="build/classes"
+ classpath="/path/to/validation-api-1.0.0.GA.jar">
+
+ <compilerarg value="-processorpath" />
+ <compilerarg
+ value="/path/to/validation-api-1.0.0.GA.jar:/path/to/hibernate-validator-annotation-processor-4.1.0-SNAPSHOT.jar"
+ />
+ </javac></programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>Maven</title>
+
+ <para>There are several options for integrating the annotation processor
+ with<ulink url="http://maven.apache.org/">Apache Maven</ulink>.
+ Generally it is sufficient to add the Hibernate Validator Annotation
+ Processor as dependency to your project:
+ </para>
+
+ <example>
+ <title>Adding the HV Annotation Processor as dependency</title>
+
+ <programlisting>...
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-validator-annotation-processor</artifactId>
+ <version>4.1.0.GA</version>
+ <scope>compile</scope>
+ </dependency>
+ ...
+ </programlisting>
+ </example>
+
+ <para>The processor will then be executed automatically by the compiler.
+ This basically works, but comes with the disadavantage that in some
+ cases messages from the annotation processor are not displayed (see
+ <ulink url="???">MCOMPILER-66</ulink>).
+ </para>
+
+ <para>Another option is using the<ulink
+ url="http://code.google.com/p/maven-annotation-plugin/">Maven Annotation
+ Plugin</ulink>. At the time of this writing the plugin is not yet
+ available in any of the well-known repositories. Therefore you have to
+ add the project's own repository to your settings.xml or pom.xml:
+ </para>
+
+ <para>
+ <example>
+ <title>Adding the Maven Annotation Plugin repository</title>
+
+ <programlisting>...
+ <pluginRepositories>
+ <pluginRepository>
+ <id>maven-annotation-plugin-repo</id>
+ <url>http://maven-annotation-plugin.googlecode.com/svn/trunk/mavenrepo</url>
+ </pluginRepository>
+ </pluginRepositories>
+ ...
+ </programlisting>
+ </example>
+ Now disable the standard annotation processing performed by
+ the compiler plugin and configure the annotation plugin by specifying an
+ execution and adding the Hibernate Validator annotation processor as
+ plugin dependency (that way the AP is not visible on the project's
+ actual classpath):
+ </para>
+
+ <example>
+ <title>Configuring the Maven Annotation Plugin</title>
+
+ <programlisting>...
+ <plugin>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <source>1.6</source>
+ <target>1.6</target>
+ <compilerArgument>-proc:none</compilerArgument>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.bsc.maven</groupId>
+ <artifactId>maven-processor-plugin</artifactId>
+ <version>1.3.4</version>
+ <executions>
+ <execution>
+ <id>process</id>
+ <goals>
+ <goal>process</goal>
+ </goals>
+ <phase>process-sources</phase>
+ </execution>
+ </executions>
+ <dependencies>
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-validator-annotation-processor</artifactId>
+ <version>4.1.0.GA</version>
+ <scope>compile</scope>
+ </dependency>
+ </dependencies>
+ </plugin>
+ ...
+ </programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>Eclipse</title>
+
+ <para>Do the following to integrate the annotation processor with the
+ Eclipse IDE:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Right-click your project, choose "Properties"</para>
+ </listitem>
+
+ <listitem>
+ <para>Go to "Java Compiler" and make sure, that "Compiler compliance
+ level" is set to "1.6", otherwise the processor won't be
+ activated
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Go to "Java Compiler - Annotation Processing" and choose
+ "Enable annotation processing"
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Go to "Java Compiler - Annotation Processing - Factory Path"
+ and add the following JARs:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>validation-api-1.0.0.GA.jar</para>
+ </listitem>
+
+ <listitem>
+ <para>hibernate-validator-annotation-processor-4.1.0.GA.jar</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Confirm the workspace rebuild</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>You now should see any annotation problems as regular error
+ markers within the editor and in the "Problem" view:
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" arch="" contentwidth="150mm"
+ fileref="annotation_processor_eclipse.png"/>
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ <section>
+ <title>IntelliJ IDEA</title>
+
+ <para>The following steps must be followed to use the annotation
+ processor within IntelliJ IDEA (version 9 and above):
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Go to "File", then "Settings",</para>
+ </listitem>
+
+ <listitem>
+ <para>Expand the node "Compiler", then "Annotation
+ Processors"
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Choose "Enable annotation processing" and enter the following
+ as "Processor path":
+ /path/to/validation-api-1.0.0.GA.jar:/path/to/hibernate-validator-annotation-processor-4.1.0.GA.jar
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Add the processor's fully qualified name
+ "org.hibernate.validator.ap.ConstraintValidationProcessor" to the
+ "Annotation Processors" list
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Add you module to the "Processed Modules" list</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Rebuilding your project then should show any erronous constraint
+ annotations:
+ </para>
+
+ <para>TODO GM: ANNOTATION_PROCESSOR_INTELLIJ.PNG</para>
+ </section>
+
+ <section>
+ <title>NetBeans</title>
+
+ <para>Starting with version 6.9, also the NetBeans IDE supports plugging
+ in annotation processors into the IDE build. To do so, do the
+ following:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Right-click your project, choose "Properties"</para>
+ </listitem>
+
+ <listitem>
+ <para>Go to "Libraries", tab "Processor", and add the following two
+ JARs:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>validation-api-1.0.0.GA.jar</para>
+ </listitem>
+
+ <listitem>
+ <para>hibernate-validator-annotation-processor-4.1.0.GA.jar</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Go to "Build - Compiling", select "Enable Annotation
+ Processing" and "Enable Annotation Processing in Editor". Add the
+ annotation processor by specifying its fully qualified name
+ org.hibernate.validator.ap.ConstraintValidationProcessor
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Any constraint annotation problems will then be marked directly
+ within the editor:
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" arch="" contentwidth="150mm"
+ fileref="annotation_processor_eclipse.png"/>
+ </imageobject>
+ </mediaobject>
+ </section>
+ </section>
+
+ <section>
+ <title>Known issues</title>
+
+ <para>TODO GM</para>
+ </section>
+</chapter>
Property changes on: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/annotationprocessor.xml
___________________________________________________________________
Name: svn:keywords
+ Id
More information about the hibernate-commits
mailing list