Chapter 2. Usage

The jar file for the annotation processor can be found in the JBoss Maven repository using Example 2.1, “Maven dependency ”.

Example 2.1. Maven dependency


<dependency>

    <groupId>org.hibernate</groupId>

    <artifactId>hibernate-jpamodelgen</artifactId>

    <version>1.0.0</version>

</dependency>

Alternatively, a full distribution package can be downloaded from SourceForge.

In most cases the annotation processor will automatically run provided the processor jar is added to the classpath and a JDK 6 is used. This happens due to Java's Service Provider contract and the fact the the Hibernate Static Metamodel Generator jar files contains the file javax.annotation.processing.Processor in the META-INF/services directory. The fully qualified name of the processor itself is: org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor.

Note

The use of a Java 6 compiler is a prerequisite.

2.1. Usage from the command line

2.1.1. Usage with Ant

As mentioned before, the annotation processor will run automatically each time the Java compiler is called, provided the jar file is on the classpath. Sometimes, however, it is useful to control the annotation processing in more detail, for example if you exclusively want to run the processor without compiling any other source files. Example 2.2, “Javac Task configuration” shows how Ant's Javac Task can be configured to just run annotation processing.

Example 2.2. Javac Task configuration


<javac srcdir="${src.dir}"

    destdir="${target.dir}"

    failonerror="false"

    fork="true"

    classpath="${classpath}">

    <compilerarg value="-proc:only"/>

</javac>

The option -proc:only instructs the compiler to just run the annotation processing. You can also completely disable processing by specifying -proc:none.

Tip

Run 'javac -help' to see which other annotation processor relevant options can be specified.

2.1.2. Usage with Maven

There are several ways of running the annotation processor as part of a Maven build. Again, it will automatically run if you are using a JDK 6 compiler and the annotation processor jar is on the classpath. In case you have more than one annotation processors on your classpath you can explicitly pass the processor option to the compiler plugin:

Example 2.3. Maven compiler plugin configuration - direct execution


<plugin>

    <artifactId>maven-compiler-plugin</artifactId>

    <configuration>

        <source>1.6</source>

        <target>1.6</target>

        <compilerArguments>

            <processor>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</processor>

        </compilerArguments>

    </configuration>

</plugin>

The maven-compiler-plugin approach has the disadvantage that the maven compiler plugin does currently not allow to specify multiple compiler arguments (MCOMPILER-62) and that messages from the Messenger API are suppressed (MCOMPILER-66). A better approach is to disable annotation processing for the compiler plugin as seen in Example 2.4, “Maven compiler plugin configuration - indirect execution”.

Example 2.4. Maven compiler plugin configuration - indirect execution


<plugin>

    <artifactId>maven-compiler-plugin</artifactId>

    <configuration>

        <source>1.6</source>

        <target>1.6</target>

        <compilerArgument>-proc:none</compilerArgument>

    </configuration>

</plugin>

Once disabled, the maven-annotation-plugin for annotation processing (you will need the following additional maven repositories: maven-annotation-plugin and jfrog) can be used. The configuration can be seen in Example 2.5, “Configuration with maven-annotation-plugin”.

Example 2.5. Configuration with maven-annotation-plugin


<plugin>

    <groupId>org.bsc.maven</groupId>

    <artifactId>maven-processor-plugin</artifactId>

    <executions>

        <execution>

            <id>process</id>

            <goals>

                <goal>process</goal>

            </goals>

            <phase>generate-sources</phase>

            <configuration>

                <!-- source output directory -->

                <outputDirectory>target/metamodel</outputDirectory>

            </configuration>

        </execution>

    </executions>

</plugin>

<plugin>

    <groupId>org.codehaus.mojo</groupId>

    <artifactId>build-helper-maven-plugin</artifactId>

    <version>1.3</version>

    <executions>

        <execution>

            <id>add-source</id>

            <phase>generate-sources</phase>

            <goals>

                <goal>add-source</goal>

            </goals>

            <configuration>

                <sources>

                    <source>target/metamodel</source>

                </sources>

            </configuration>

        </execution>

    </executions>

</plugin>

In Eclipse, from the Galileo release onwards, exists an additional configuration section under Java Compiler. There you can configure all kinds of aspects of annotation processing. Just check the "Enable annotation processing" option, configure the directory for the generated sources and finally add the Hibernate Static Metamodel Generator and JPA 2 jar files to the factory path.

2.2.3. NetBeans

Netbeans support for annotation processors is at the time of this wrinting still in the making. Refer to NetBeans issues 111065, 111293 and 111294.

2.3. Processor specific options

The Hibernate Static Metamodel Generator accepts a series of custom options which can be passed to the processor in the format -A[property]=[value]. The supported properties are:

Table 2.1. Annotation processor options (passed via -A[property]=[value])

Option name	Option value and usage
debug	if set to `true` additional trace information will be outputted by the processor
persistenceXml	Per default the processor looks in `/META-INF` for persistence.xml. Specifying this option a `persitence.xml` file from a different location can be specified (has to be on the classpath)
ormXml	Allows to specify additional entity mapping files. The specified value for this option is a comma separated string of mapping file names. Even when this option is specified `/META-INF/orm.xml` is implicit.
lazyXmlParsing	Possible values are `true` or `false`. If set to `true` the annotation processor tries to determine whether any of the xml files has changed between invocations and if unchanged skips the xml parsing. This feature is experimental and contains the risk of wron results in some cases of mixed mode configurations. To determine wether a file has been modified a temporary file `Hibernate-Static-Metamodel-Generator.tmp` is used. This file gets created in the `java.io.tmpdir` directory.