JPA Metamodel API

The JPA Metamodel API provides the ability to examine the persistent object model and retrieve details on managed classes and persistent fields and properties, similarly to the ability that Java reflection provides for general Java types.

The Metamodel Interface

The main interface of the JPA Metamodel API is Metamodeljavax.persistence.metamodel.MetamodelJPA interfaceProvides access to the metamodel of persistent entities in the persistence unit.See JavaDoc Reference Page.... It can be obtained either by the EntityManagerFactoryjavax.persistence.EntityManagerFactoryJPA interfaceInterface used to interact with the entity manager factory for the persistence unit.See JavaDoc Reference Page...'s getMetamodelgetMetamodel()EntityManagerFactory's methodReturn an instance of Metamodel interface for access to the metamodel of the persistence unit.See JavaDoc Reference Page... method or by the EntityManagerjavax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page...'s getMetamodelgetMetamodel()EntityManager's methodReturn an instance of Metamodel interface for access to the metamodel of the persistence unit.See JavaDoc Reference Page... method (both methods are equivalent).

For example, given an EntityManagerjavax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page..., em, a Metamodel instance can be obtained by:

  Metamodeljavax.persistence.metamodel.MetamodelJPA interfaceProvides access to the metamodel of persistent
 entities in the persistence unit.See JavaDoc Reference Page... metamodel = em.getMetamodelgetMetamodel()EntityManager's methodReturn an instance of Metamodel interface for access to the
 metamodel of the persistence unit.See JavaDoc Reference Page...();

The Metamodeljavax.persistence.metamodel.MetamodelJPA interfaceProvides access to the metamodel of persistent entities in the persistence unit.See JavaDoc Reference Page... interface provides several methods for exploring user defined persistable types (which are referred to as managed types) in the persistent object model.

Three methods can be used to retrieve sets of types:

  // Get all the managed classes:
  // (entity classes, embeddable classes, mapped super classes)
  Set<ManagedTypejavax.persistence.metamodel.ManagedTypeJPA interfaceInstances of the type ManagedType represent entity, mapped 
  superclass, and embeddable types.See JavaDoc Reference Page...> allManagedTypes = metamodel.getManagedTypesgetManagedTypes()Metamodel's methodReturn the metamodel managed types.See JavaDoc Reference Page...();

  // Get all the entity classes:
  Set<EntityTypejavax.persistence.metamodel.EntityTypeJPA interfaceInstances of the type EntityType represent entity types.See JavaDoc Reference Page...> allEntityTypes = metamodel.getEntitiesgetEntities()Metamodel's methodReturn the metamodel entity types.See JavaDoc Reference Page...();

  // Get all the embeddable classes:
  Set<EmbeddableTypejavax.persistence.metamodel.EmbeddableTypeJPA interfaceInstances of the type EmbeddableType represent embeddable types.See JavaDoc Reference Page...> allEmbeddableTypes = metamodel.getEmbeddablesgetEmbeddables()Metamodel's methodReturn the metamodel embeddable types.See JavaDoc Reference Page...();

If managed classes are not listed in the persistence unit (which is optional when using ObjectDB) then only known managed types are returned. This includes all the types whose instances are already stored in the database.

Three additional methods can be used to retrieve a specific type by its Class instance:

  // Get a managed type (entity, embeddable or mapped super classes):
  ManagedTypejavax.persistence.metamodel.ManagedTypeJPA interfaceInstances of the type ManagedType represent entity, mapped 
  superclass, and embeddable types.See JavaDoc Reference Page...<MyClass> type1 = metamodel.managedTypemanagedType(cls)Metamodel's methodReturn the metamodel managed type representing the 
  entity, mapped superclass, or embeddable class.See JavaDoc Reference Page...(MyClass.class);

  // Get an entity type:
  EntityTypejavax.persistence.metamodel.EntityTypeJPA interfaceInstances of the type EntityType represent entity types.See JavaDoc Reference Page...<MyEntity> type2 = metamodel.entityentity(cls)Metamodel's methodReturn the metamodel entity type representing the entity.See JavaDoc Reference Page...(MyEntity.class);

  // Get an embeddable type:
  EmbeddableTypejavax.persistence.metamodel.EmbeddableTypeJPA interfaceInstances of the type EmbeddableType represent embeddable types.See JavaDoc Reference Page...<MyEmbeddableType> type3 =
      metamodel.embeddableembeddable(cls)Metamodel's methodReturn the metamodel embeddable type representing the
  embeddable class.See JavaDoc Reference Page...(MyEmbeddableType.class);

These three methods can also be used with types that are still unknown to ObjectDB (not listed in the persistence unit and have not been used yet). In this case, calling the method introduces the specified type to ObjectDB.

Type Interface Hierarchy

Types are represented in the Metamodel API by descendant interfaces of the Typejavax.persistence.metamodel.TypeJPA interfaceInstances of the type Type represent persistent object or attribute types.See JavaDoc Reference Page... interface:

• BasicTypejavax.persistence.metamodel.BasicTypeJPA interfaceInstances of the type BasicType represent basic types (including temporal and enumerated types).See JavaDoc Reference Page... - represents system defined types.
• ManagedTypejavax.persistence.metamodel.ManagedTypeJPA interfaceInstances of the type ManagedType represent entity, mapped superclass, and embeddable types.See JavaDoc Reference Page... is an ancestor of interfaces that represent user defined types:
  • EmbeddableTypejavax.persistence.metamodel.EmbeddableTypeJPA interfaceInstances of the type EmbeddableType represent embeddable types.See JavaDoc Reference Page... - represents user defined embeddable classes.
  • IdentifiableTypejavax.persistence.metamodel.IdentifiableTypeJPA interfaceInstances of the type IdentifiableType represent entity or mapped superclass types.See JavaDoc Reference Page... is as a super interface of:
    • MappedSuperclassTypejavax.persistence.metamodel.MappedSuperclassTypeJPA interfaceInstances of the type MappedSuperclassType represent mapped superclass types.See JavaDoc Reference Page... - represents user defined mapped super classes.
    • EntityTypejavax.persistence.metamodel.EntityTypeJPA interfaceInstances of the type EntityType represent entity types.See JavaDoc Reference Page... - represents user defined entity classes.

The Typejavax.persistence.metamodel.TypeJPA interfaceInstances of the type Type represent persistent object or attribute types.See JavaDoc Reference Page... interface provides a thin wrapper of Class with only two methods:

  // Get the underlying Java representation of the type:
  Class cls = type.getJavaTypegetJavaType()Type's methodReturn the represented Java type.See JavaDoc Reference Page...();

  // Get one of BASIC, EMBEDDABLE, ENTITY, MAPPED_SUPERCLASS:
  PersistenceType kind = type.getPersistenceTypegetPersistenceType()Type's methodReturn the persistence type.See JavaDoc Reference Page...();

The ManagedTypejavax.persistence.metamodel.ManagedTypeJPA interfaceInstances of the type ManagedType represent entity, mapped superclass, and embeddable types.See JavaDoc Reference Page... interface adds methods for exploring managed fields and properties (which are referred to as attributes). For example:

  // Get all the attributes - including inherited:
  Set<Attributejavax.persistence.metamodel.AttributeJPA interfaceRepresents an attribute of a Java type.See JavaDoc Reference Page...> attributes1 = managedType.getAttributesgetAttributes()ManagedType's methodReturn the attributes of the managed type.See JavaDoc Reference Page...();

  // Get all the attributes - excluding inherited:
  Set<Attributejavax.persistence.metamodel.AttributeJPA interfaceRepresents an attribute of a Java type.See JavaDoc Reference Page...> attributes2 = managedType.getDeclaredAttributesgetDeclaredAttributes()ManagedType's methodReturn the attributes declared by the managed type.See JavaDoc Reference Page...();

  // Get a specific attribute - including inherited:
  Attributejavax.persistence.metamodel.AttributeJPA interfaceRepresents an attribute of a Java type.See JavaDoc Reference Page...<MyClass,String> strAttr1 = managedType.getAttributegetAttribute(name)ManagedType's methodReturn the attribute of the managed
  type that corresponds to the specified name.See JavaDoc Reference Page...("name");

  // Get a specific attribute - excluding inherited:
  Attributejavax.persistence.metamodel.AttributeJPA interfaceRepresents an attribute of a Java type.See JavaDoc Reference Page...<MyClass,String> strAttr2 =
      managedType.getDeclaredAttributegetDeclaredAttribute(name)ManagedType's methodReturn the attribute declared by the managed
  type that corresponds to the specified name.See JavaDoc Reference Page...("name");

Additional methods are defined in ManagedTypejavax.persistence.metamodel.ManagedTypeJPA interfaceInstances of the type ManagedType represent entity, mapped superclass, and embeddable types.See JavaDoc Reference Page... to return attributes of Collection, List, Set a Map types in a type safe manner.

The IdentifiableTypejavax.persistence.metamodel.IdentifiableTypeJPA interfaceInstances of the type IdentifiableType represent entity or mapped superclass types.See JavaDoc Reference Page... adds methods for retrieving information on the primary key and the version attributes and the super type. For example:

  // Get the super type:
  IdentifiableTypejavax.persistence.metamodel.IdentifiableTypeJPA interfaceInstances of the type IdentifiableType represent entity or 
  mapped superclass types.See JavaDoc Reference Page...<MyEntity> superType = entityType.getSupertypegetSupertype()IdentifiableType's methodReturn the identifiable type that corresponds to the most
  specific mapped superclass or entity extended by the entity 
  or mapped superclass.See JavaDoc Reference Page...();

  // Checks if the type has a single ID attribute:
  boolean hasSingleId = entityType.hasSingleIdAttributehasSingleIdAttribute()IdentifiableType's methodWhether the identifiable type has a single id attribute.See JavaDoc Reference Page...();

  // Gets a single ID attribute - including inherited:
  SingularAttributejavax.persistence.metamodel.SingularAttributeJPA interfaceInstances of the type SingularAttribute represents persistent 
 single-valued properties or fields.See JavaDoc Reference Page...<MyEntity,Long> id1 = entityType.getIdgetId(type)IdentifiableType's methodReturn the attribute that corresponds to the id attribute of 
  the entity or mapped superclass.See JavaDoc Reference Page...(Long.class);

  // Gets a single ID attribute - excluding inherited:
  SingularAttributejavax.persistence.metamodel.SingularAttributeJPA interfaceInstances of the type SingularAttribute represents persistent 
 single-valued properties or fields.See JavaDoc Reference Page...<MyEntity,Long> id2 =
      entityType.getDeclaredIdgetDeclaredId(type)IdentifiableType's methodReturn the attribute that corresponds to the id attribute 
  declared by the entity or mapped superclass.See JavaDoc Reference Page...(Long.class);

  // Checks if the type has a version attribute:
  boolean hasVersion = entityType.hasVersionAttributehasVersionAttribute()IdentifiableType's methodWhether the identifiable type has a version attribute.See JavaDoc Reference Page...();

  // Gets the version attribute - excluding inherited:
  SingularAttributejavax.persistence.metamodel.SingularAttributeJPA interfaceInstances of the type SingularAttribute represents persistent 
 single-valued properties or fields.See JavaDoc Reference Page...<MyEntity,Long> v1 = entityType.getVersiongetVersion(type)IdentifiableType's methodReturn the attribute that corresponds to the version 
  attribute of the entity or mapped superclass.See JavaDoc Reference Page...(Long.class);

  // Gets the version attribute - including inherited:
  SingularAttributejavax.persistence.metamodel.SingularAttributeJPA interfaceInstances of the type SingularAttribute represents persistent 
 single-valued properties or fields.See JavaDoc Reference Page...<MyEntity,Long> v2 =
      entityType.getDeclaredVersiongetDeclaredVersion(type)IdentifiableType's methodReturn the attribute that corresponds to the version 
  attribute declared by the entity or mapped superclass.See JavaDoc Reference Page...(Long.class);

Additional methods are defined in IdentifiableTypejavax.persistence.metamodel.IdentifiableTypeJPA interfaceInstances of the type IdentifiableType represent entity or mapped superclass types.See JavaDoc Reference Page... to support an ID class when using multiple ID fields or properties.

Finally, the EntityTypejavax.persistence.metamodel.EntityTypeJPA interfaceInstances of the type EntityType represent entity types.See JavaDoc Reference Page... interface adds only one additional method for getting the entity name:

  String entityName = entityType.getNamegetName()EntityType's methodReturn the entity name.See JavaDoc Reference Page...();

Attribute Interface Hierarchy

Managed fields and properties are represented by the Attributejavax.persistence.metamodel.AttributeJPA interfaceRepresents an attribute of a Java type.See JavaDoc Reference Page... interface and its descendant interfaces:

• SingularAttributejavax.persistence.metamodel.SingularAttributeJPA interfaceInstances of the type SingularAttribute represents persistent single-valued properties or fields.See JavaDoc Reference Page... - represents single value attributes.
• PluralAttributejavax.persistence.metamodel.PluralAttributeJPA interfaceInstances of the type PluralAttribute represent persistent collection-valued attributes.See JavaDoc Reference Page... is an ancestor of interfaces that represent multi value attributes:
  • CollectionAttributejavax.persistence.metamodel.CollectionAttributeJPA interfaceInstances of the type CollectionAttribute represent persistent java.util.Collection-valued attributes.See JavaDoc Reference Page... - represents attributes of Collection types.
  • SetAttributejavax.persistence.metamodel.SetAttributeJPA interfaceInstances of the type SetAttribute represent persistent java.util.Set-valued attributes.See JavaDoc Reference Page... - represents attributes of Set types.
  • ListAttributejavax.persistence.metamodel.ListAttributeJPA interfaceInstances of the type ListAttribute represent persistent javax.util.List-valued attributes.See JavaDoc Reference Page... represents attributes of List types.
  • MapAttributejavax.persistence.metamodel.MapAttributeJPA interfaceInstances of the type MapAttribute represent persistent java.util.Map-valued attributes.See JavaDoc Reference Page... - represents attributes of Map types.

The Attributejavax.persistence.metamodel.AttributeJPA interfaceRepresents an attribute of a Java type.See JavaDoc Reference Page... interface provides methods for retrieving field and property details. For example:

  // Get the field (or property) name:
  String name = attr.getNamegetName()Attribute's methodReturn the name of the attribute.See JavaDoc Reference Page...();

  // Get Java representation of the field (or property) type:
  Class<Integer> attr.getJavaTypegetJavaType()Attribute's methodReturn the Java type of the represented attribute.See JavaDoc Reference Page...();

  // Get Java reflection representation of the field (or property) type:
  Member member = attr.getJavaMembergetJavaMember()Attribute's methodReturn the java.lang.reflect.Member for the represented 
  attribute.See JavaDoc Reference Page...();

  // Get the type in which this field (or property) is defined:
  ManagedTypejavax.persistence.metamodel.ManagedTypeJPA interfaceInstances of the type ManagedType represent entity, mapped 
  superclass, and embeddable types.See JavaDoc Reference Page...<MyEntity> entityType = attr.getDeclaringTypegetDeclaringType()Attribute's methodReturn the managed type representing the type in which 
  the attribute was declared.See JavaDoc Reference Page...();

Few other methods are defined in Attributejavax.persistence.metamodel.AttributeJPA interfaceRepresents an attribute of a Java type.See JavaDoc Reference Page... and in MapAttributejavax.persistence.metamodel.MapAttributeJPA interfaceInstances of the type MapAttribute represent persistent java.util.Map-valued attributes.See JavaDoc Reference Page... to support additional details.