Java Platform, Enterprise Edition: The Java EE Tutorial

40.2 Using the Metamodel API to Model Entity Classes

Use the Metamodel API to create a metamodel of the managed entities in a particular persistence unit. For each entity class in a particular package, a metamodel class is created with a trailing underscore and with attributes that correspond to the persistent fields or properties of the entity class.

The following entity class, com.example.Pet, has four persistent fields: id, name, color, and owners:

package com.example;
public class Pet {
    protected Long id;
    protected String name;
    protected String color;
    protected Set<Person> owners;

The corresponding Metamodel class is as follows:

package com.example;
@Static Metamodel(Pet.class)
public class Pet_ {

    public static volatile SingularAttribute<Pet, Long> id;
    public static volatile SingularAttribute<Pet, String> name;
    public static volatile SingularAttribute<Pet, String> color;
    public static volatile SetAttribute<Pet, Person> owners;

Criteria queries use the metamodel class and its attributes to refer to the managed entity classes and their persistent state and relationships.

40.2.1 Using Metamodel Classes

Metamodel classes that correspond to entity classes are of the following type:


Annotation processors typically generate metamodel classes either at development time or at runtime. Developers of applications that use Criteria queries may do either of the following:

  • Generate static metamodel classes by using the persistence provider's annotation processor

  • Obtain the metamodel class by doing one of the following:

    • Call the getModel method on the query root object

    • Obtain an instance of the Metamodel interface and then pass the entity type to the instance's entity method

The following code snippet shows how to obtain the Pet entity's metamodel class by calling Root<T>.getModel:

EntityManager em = ...;
CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery cq = cb.createQuery(Pet.class);
Root<Pet> pet = cq.from(Pet.class);
EntityType<Pet> Pet_ = pet.getModel();

The following code snippet shows how to obtain the Pet entity's metamodel class by first obtaining a metamodel instance by using EntityManager.getMetamodel and then calling entity on the metamodel instance:

EntityManager em = ...;
Metamodel m = em.getMetamodel();
EntityType<Pet> Pet_ = m.entity(Pet.class);


The most common use case is to generate typesafe static metamodel classes at development time. Obtaining the metamodel classes dynamically, by calling Root<T>.getModel or EntityManager.getMetamodel and then the entity method, doesn't allow for type safety and doesn't allow the application to call persistent field or property names on the metamodel class.
Close Window

Table of Contents

Java Platform, Enterprise Edition: The Java EE Tutorial

Expand | Collapse