Hibernate.orgCommunity Documentation

Chapter 1. Introduction

1.1. What is it about?
1.2. Canonical Metamodel

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.




Tip

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:

<persistence-unit-metadata>
  <xml-mapping-metadata-complete/>
</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.