Hibernate.orgCommunity Documentation

Chapter 2. Usage

2.1. Usage from the command line
2.1.1. Usage with Ant
2.1.2. Usage with Maven
2.2. Usage within the IDE
2.2.1. Idea
2.2.2. Eclipse
2.2.3. NetBeans
2.3. Processor specific options

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.

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:


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


Once disabled, the maven-processor-plugin for annotation processing can be used. The configuration can be seen in Example 2.5, “Configuration with maven-processor-plugin”.


Of course you also want to have annotation processing available in your favorite IDE. The following paragraphs and screenshots show you how to enable the Hibernate Static Metamodel Generator within your IDE.

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 nameOption value and usage
debugIf set to true additional trace information will be outputted by the processor
persistenceXmlPer 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)
ormXmlAllows 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.
lazyXmlParsingPossible 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.
fullyAnnotationConfiguredIf set to true the processor will ignore orm.xml and persistence.xml.
addGeneratedAnnotationIf set to true the processor will add the @Generated to the generated Java source file. Adding this annotation using JDK 5will cause a compilation error. In this case set the flag to false. The default for this option is true
addGenerationDateIf set to true the generation date of the metamodel class will be inserted in the date parameter of the @Generated annotation. The default is false. This parameter is ignored if addGeneratedAnnotation is set to false.
addSuppressWarningsAnnotationIf set to true the processor will add @SuppressWarnings("all") to the generated Java source file. Per default this annotation is not generated. See also METAGEN-50.