Chapter 1. Introduction

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.

Example 1.1. JPA 2 annotated entities Order and Item



@Entity

public class Order {

    @Id 

    @GeneratedValue

    Integer id;

    

    @ManyToOne 

    Customer customer;

    

    @OneToMany 

    Set<Item> items;

    BigDecimal totalCost;

    

    // standard setter/getter methods

    ...

}


@Entity  

public class Item { 

    @Id

    @GeneratedValue

      Integer id;

    

      int quantity;

        

    @ManyToOne

    Order order;

    

    // standard setter/getter methods

    ...

}

Example 1.2. Metamodel class Order_



@StaticMetamodel(Order.class)

public class Order_ {

    public static volatile SingularAttribute<Order, Integer> id;

    public static volatile SingularAttribute<Order, Customer> customer;

    public static volatile SetAttribute<Order, Item> items;

    public static volatile SingularAttribute<Order, BigDecimal> totalCost;

}

Example 1.3. Typesafe citeria query



CriteriaBuilder cb = entityManager.getCriteriaBuilder();

CriteriaQuery<Order> cq = cb.createQuery(Order.class);

SetJoin<Order, Item> itemNode = cq.from(Order.class).join(Order_.items);

cq.where( cb.equal(itemNode.get(Item_.id), 5 ) ).distinct(true);

1.2. Canonical Metamodel

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.

Chapter 1. Introduction

1.1. What is it about?

1.2. Canonical Metamodel