The JPA 2 metamodel is the cornerstone of type-safe criteria queries in JPA 2. The generated classes allow you to refer to entity properties using static field references, instead of strings. (A metamodel class is the fully-qualified class name of the entity class it matches followed by an underscore (_)).

It sounds promising, but many people using Maven are getting tripped up trying to get the metamodel generated and compiled. The Hibernate JPA 2 Metamodel Generator guide offers a couple of solutions. I've figured out another, which seems more elegant.

Just to refresh your memory of the problem:

  1. Maven compiles the classes during the compile phase
  2. The Java 6 compiler allows annotation processors to hook into it
  3. Annotation processors are permitted to generate Java source files (which is the case with the JPA 2 metamodel)
  4. Maven does not execute a secondary compile step to compile Java source files generated by the annotation processor

I figured out that it's possible to use the Maven compiler plugin to run only the annotation processors during the generate-sources phase! This effectively becomes a code generation step. Then comes the only downside. If you can believe it, Maven does not have a built-in way to compile generated sources. So we have to add one more plugin (build-helper-maven-plugin) that simply adds an additional source folder (I really can't believe the compiler plugin doesn't offer this feature). During the compile phase, we can disable the annotation processors to speed up compilation and avoid generating the metamodel a second time.

Here's the configuration for your copy-paste pleasure. Add it to the <plugins> section of your POM.

<!-- Compiler plugin enforces Java 1.6 compatibility and controls execution of annotation processors -->
<plugin>
   <artifactId>maven-compiler-plugin</artifactId>
   <version>2.3.1</version>
   <configuration>
      <source>1.6</source>
      <target>1.6</target>
      <compilerArgument>-proc:none</compilerArgument>
   </configuration>
   <executions>
      <execution>
         <id>run-annotation-processors-only</id>
         <phase>generate-sources</phase>
         <configuration>
            <compilerArgument>-proc:only</compilerArgument>
            <!-- If your app has multiple packages, use this include filter to
                 execute the processor only on the package containing your entities -->
            <!--
            <includes>
               <include>**/model/*.java</include>
            </includes>
            -->
         </configuration>
         <goals>
            <goal>compile</goal>
         </goals>
      </execution>
   </executions>  
</plugin>         
<!-- Build helper plugin adds the sources generated by the JPA 2 annotation processor to the compile path -->
<plugin>
   <groupId>org.codehaus.mojo</groupId>
   <artifactId>build-helper-maven-plugin</artifactId>
   <version>1.5</version>
   <executions>      
      <execution> 
         <phase>process-sources</phase>
         <configuration>
            <sources>
               <source>${project.build.directory}/generated-sources/annotations</source>
            </sources>
         </configuration>
         <goals>
            <goal>add-source</goal>
         </goals>
      </execution>
   </executions>
</plugin>

The metamodel source files get generated into the target/generated-sources/annotations directory.

Note that if you have references to the metamodel across Java packages, you'll need to filter the annotation processor to only run on the package containing the entity classes.

We'll be protoyping this approach in the 1.0.1.Beta1 release of the Weld archetypes, which should be out soon.

Bonus material: Eclipse configuration

While I'm at it, I might as well show you how I enabled the JPA 2 metamodel generation in Eclipse. (Max may correct me. He's the authority on Eclipse tooling, so listen to what he says).

Start by adding the following dependency to your POM:

<dependency>
   <groupId>org.hibernate</groupId>
   <artifactId>hibernate-jpamodelgen</artifactId>
   <version>1.0.0.Final</version>
   <scope>provided</scope>
</dependency>

Then, populate the .factorypath file at the root of your project with the following contents:

<factorypath>
    <factorypathentry kind="PLUGIN" id="org.eclipse.jst.ws.annotations.core" enabled="true" runInBatchMode="false"/>
    <factorypathentry kind="VARJAR" id="M2_REPO/org/hibernate/hibernate-jpamodelgen/1.0.0.Final/hibernate-jpamodelgen-1.0.0.Final.jar" enabled="true" runInBatchMode="false"/>
    <factorypathentry kind="VARJAR" id="M2_REPO/org/hibernate/javax/persistence/hibernate-jpa-2.0-api/1.0.0.Final/hibernate-jpa-2.0-api-1.0.0.Final.jar" enabled="true" runInBatchMode="false"/>
</factorypath>

Refresh the project in Eclipse. Now right click on the project and select:

Properties > Java Compiler > Annotation Processing

Enable project specific settings and enable annotation processing. Press OK and OK again when prompted to build the project. Now, Eclipse should also generate your JPA 2 metamodel.

Happy type-safe criteria querying!


Back to top