Hibernate.orgCommunity Documentation

Hibernate JPA 2 Metamodel Generator

Reference Guide

JPA 2 defines a new typesafe Criteria API which allows criteria queries to be constructed in a strongly-typed manner, using metamodel objects to provide type safety. For developers it is important that the task of the metamodel generation can be automated. Hibernate Static Metamodel Generator is an annotation processor based on the [Pluggable Annotation Processing API] with the task of creating JPA 2 static metamodel classes. The following example show two JPA 2 entities Order and Item, together with the metamodel class Order_ and a typesafe query.


The Metamodel Generator also takes into consideration xml configuration specified in orm.xml or mapping files specified in persistence.xml. However, if all configuration is in XML you need to add in at least on of the mapping file the following persistence unit metadata:


The structure of the metamodel classes is described in the [JPA 2 Specification], but for completeness the definition is repeated in the following paragraphs. Feel free to skip ahead to Chapter 2, Usage if you are not interested into the gory details.

The annotation processor produces for every managed class in the persistence unit a metamodel class based on these rules:

  • For each managed class X in package p, a metamodel class X_ in package p is created.

  • The name of the metamodel class is derived from the name of the managed class by appending "_" to the name of the managed class.

  • The metamodel class X_ must be annotated with the javax.persistence.StaticMetamodel annotation.

  • If class X extends another class S, where S is the most derived managed class (i.e., entity or mapped superclass) extended by X, then class X_ must extend class S_, where S_ is the metamodel class created for S.

  • For every persistent non-collection-valued attribute y declared by class X, where the type of y is Y, the metamodel class must contain a declaration as follows:

    public static volatile SingularAttribute<X, Y> y;
  • For every persistent collection-valued attribute z declared by class X, where the element type of z is Z, the metamodel class must contain a declaration as follows:

    • if the collection type of z is java.util.Collection, then

      public static volatile CollectionAttribute<X, Z> z;
    • if the collection type of z is java.util.Set, then

      public static volatile SetAttribute<X, Z> z;
    • if the collection type of z is java.util.List, then

      public static volatile ListAttribute<X, Z> z;
    • if the collection type of z is java.util.Map, then

      public static volatile MapAttribute<X, K, Z> z;

      where K is the type of the key of the map in class X

Import statements must be included for the needed javax.persistence.metamodel types as appropriate and all classes X, Y, Z, and K.

The jar file for the annotation processor can be found in the JBoss Maven repository using Example 2.1, “Maven 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.


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:

For further usage question or problems consult the Hibernate Forum. For bug reports use the METAGEN project in the Hibernate Jira instance. Feedback is always welcome.