Metamodel classes for OpenJPA with Maven, Eclipse and m2e

Metamodel classes are a not-so-well known feature of the JPA 2.0 standard. They allow you to write typesafe criteria queries using metamodel attributes instead of plain old strings to reference entity fields. (See this tutorial for some more background.)

Metamodel classes are generated by an annotation processor during the build process, but this is not enabled by default. OpenJPA logs a runtime warning when you build a criteria query and the metamodel classes cannot be found. So even if you don't use the metamodel, you may want to generate it just to get rid of this warning.

This article explains how to generate the metamodel both in Maven batch builds and in the Eclipse workspace.


According to the OpenJPA Manual, the following POM snippet should be sufficient to generate the metamodel:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>2.3.2</version>
  <configuration>
    <source>1.6</source>
    <target>1.6</target>
    <compilerArgument>-Aopenjpa.metamodel=true -Aopenjpa.log=TRACE</compilerArgument>
  </configuration>
</plugin>

Unfortunately, this does not work due to a bug in the Maven Compiler Plugin, which does not handle multiple compiler arguments correctly - the alternative configuration element <compilerArguments> (note the plural) does not work either. So make sure to use only one compiler argument without any blank spaces (the log option is not required anyway):

<compilerArgument>-Aopenjpa.metamodel=true</compilerArgument>

After this change, the OpenJPA annotation processor should be triggered when running mvn compile.

You may now hit the next problem with the following exception:

java.lang.ClassCastException: com.sun.tools.javac.code.Symbol$PackageSymbol 
cannot be cast to javax.lang.model.element.TypeElement 

which is caused by the OpenJPA annotation processor choking on a package-info.java file. This is a bug fixed in OpenJPA 2.2.0, so if you see this exception, upgrade OpenJPA or delete any package-info.java.

If you don't work with Eclipse, this is all you need to know.

For Eclipse + m2e users, some more tweaking is required, as the Eclipse Java compiler does not pick up the annotation processor option automatically. The preferred solution, an m2e extension for annotation processing, is not yet available, and the best approach I've found so far is not really straightforward but nonetheless effective. It requires three steps:

• Annotation processing is performed by the Maven Processor Plugin in the generate-sources phase.
• The directory with the generated sources is made known to the compiler with the Maven Build Helper Plugin.
• This directory will be picked up by the Eclipse compiler when the m2e buildhelper connector is installed.

So first of all, install the m2e buildhelper connector via Window | Preferences | Maven | Discovery | Open Catalog. Then remove the <compilerArgument> from the maven-compiler-plugin configuration and add the following to your POM:

<plugin>
  <groupId>org.bsc.maven</groupId>
  <artifactId>maven-processor-plugin</artifactId>
  <version>2.0.5</version>
  <executions>
    <execution>
      <id>process</id>
      <goals>
        <goal>process</goal>
      </goals>
      <phase>generate-sources</phase>
      <configuration>
        <processors>
          <processor>org.apache.openjpa.persistence.meta.AnnotationProcessor6</processor>
        </processors>
        <optionMap>
          <openjpa.metamodel>true</openjpa.metamodel>
        </optionMap>
      </configuration>
    </execution>
  </executions>
</plugin>
<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>build-helper-maven-plugin</artifactId>
  <version>1.7</version>
  <executions>
    <execution>
      <id>add-source</id>
      <phase>generate-sources</phase>
      <goals>
        <goal>add-source</goal>
      </goals>
      <configuration>
        <sources>
          <source>${project.build.directory}/generated-sources/apt</source>
        </sources>
      </configuration>
    </execution>
  </executions>
</plugin>

Then run Maven | Update Project Configuration from the context menu of your Eclipse project. The metamodel classes will now be generated whenever Eclipse rebuilds your project.