4 Understanding Entities

This chapter introduces and describes entities. An entity is a lightweight persistence domain object. Typically, an entity represents a table in a relational database, and each entity instance corresponds to a row in the table. The primary programming artifact of an entity is the entity class, although entities can use helper classes.

The persistent state of an entity is represented either through persistent fields or persistent properties. These fields or properties use object/relational mapping annotations to map the entities and entity relationships to the relational data in the underlying data store.

You can configure your entity's identity, as well as the locking technique and sequence generation options for your entity.

This chapter includes the following sections:

4.1 Identifying Entities

Use the @Entity annotation to specify that a class is an entity.

Note:

The entity class must also be listed in your persistence.xml file, unless you set the tag <exclude-unlisted-classes> to false.

For more information, see Chapter 2 "Entities" in the JPA Specification.

http://jcp.org/en/jsr/detail?id=338

4.2 Entities and Persistent Identity

Every entity must have a persistent identity, which is an equivalent of a primary key in a database table that stores the entity state.

By default, the EclipseLink persistence provider assumes that each entity has at least one field or property that serves as a primary key.

You can generate and/or configure the identity of your entities by using the following annotations:

  • @Id

  • @IdClass

  • @EmbeddedId

  • @GeneratedValue

  • @TableGenerator

  • @SequenceGenerator

  • @UuidGenerator

You can also use these annotations to fine-tune how your database maintains the identity of your entities. For more information on these annotations, see "Metadata for Object/Relational Mapping" in the JPA Specification.

http://jcp.org/en/jsr/detail?id=338

4.3 Entities and Database Tables

Every entity class maps to a specific table or set of tables in the database. By default, the entity's table name is defaulted as its entity name as uppercase, which defaults to the entity's short class name. An entity normally maps to a single table, but can also map to multiple tables, or even a view.

You can customize an entity's tables using the following annotations:

  • @Table

  • @SecondaryTable

4.4 Entities and Inheritance

JPA defines several difference methods for persisting objects with inheritance. The @Inheritance annotation is used in the root class to define SINGLE_TABLE, JOINED, and TABLE_PER_CLASS inheritance. For abstract classes that define common state or persistence behavior, but have no relationship on the database, the @MappedSuperclass annotation can be used.

  • @Inheritance

  • @MappedSuperclass

4.5 Entities and Embedded Objects

You can use the @Embeddable annotation to map an embedded class. An embeddable is a special type of class that is not directly persistent, but persisted only with its parent entity. An embeddable can be referenced from an entity or another embeddable using the @Embedded annotation for a single reference, @EmbeddedId for an embedded id, or the @ElementCollection annotation for a Collection or Map reference. An embeddable can also be used in any Map key using the @MapKeyClass annotation.

  • @Embeddable

  • @EmbeddedId

  • @Embedded

  • @ElementCollection

4.6 Entities and Sequence Generation

Many databases support an internal mechanism for id generation called sequences. You can use a database sequence to generate identifiers when the underlying database supports them.

  • @SequenceGenerator—If you use the @GeneratedValue annotation to specify a primary key generator of type SEQUENCE, then you can use the @SequenceGenerator annotation to fine-tune this primary key generator to do the following:

    • change the allocation size to match your application requirements or database performance parameters

    • change the initial value to match an existing data model (for example, if you are building on an existing data set for which a range of primary key values has already been assigned or reserved)

    • use a predefined sequence in an existing data model

  • @TableGenerator—If you use the @GeneratedValue annotation to specify a primary key generator of type TABLE, then you can use the @TableGenerator annotation to fine-tune this primary key generator to do the following:

    • change the name of the primary key generator's table, because the name is awkward, a reserved word, incompatible with a preexisting data model, or invalid as a table name in your database

    • change the allocation size to match your application requirements or database performance parameters

    • change the initial value to match an existing data model (for example, if you are building on an existing data set, for which a range of primary key values has already been assigned or reserved)

    • configure the primary key generator's table with a specific catalog or schema

    • configure a unique constraint on one or more columns of the primary key generator's table

For more information and examples of these annotations, see "Metadata for Object/Relational Mapping" in the JPA Specification.

4.7 Entities and Locking

You have the choice between optimistic and pessimistic locking. Oracle recommends using optimistic locking. For more information, see Section 5.2.4, "Descriptors and Locking."

By default, the EclipseLink persistence provider assumes that the application is responsible for data consistency.

Oracle recommends that you use the @Version annotation to enable JPA-managed optimistic locking by specifying the version field or property of an entity class that serves as its optimistic lock value. When choosing a version field or property, ensure that the following is true:

  • there is only one version field or property per entity

  • you choose a property or field persisted to the primary table (see "Table Annotation" in the JPA Specification)

  • your application does not modify the version property or field

Note:

The field or property type must either be a numeric type (such as Number, long, int, BigDecimal, and so on), or a java.sql.Timestamp. Oracle recommends using a numeric type.

The @Version annotation does not have attributes.

For more information, see the following:

For more information on the EclipseLink artifacts configured by JPA metadata, see Section 5.2.4, "Descriptors and Locking".

4.8 Extensible Entities

JPA entities and JAXB beans can be made extensible by adding or modifying mappings externally. There is no need to modify the entity or bean source file nor do you have to redeploy the persistence unit.

Extensible entities are useful in a multi-tenant (or SaaS) architecture where a shared, generic application can be used by multiple clients (tenants). Tenants have private access to their own data, and to data shared with other tenants.

Using extensible entities, you can:

  • Build an application where some mappings are common to all users and some mappings are user-specific.

  • Add mappings to an application after it is made available to a customer (even post-deployment).

  • Use the same EntityManagerFactory interface to work with data after mappings have changed.

  • Provide an additional source of metadata to be used by an application.

Use the @VirtualAccessMethods annotation to specify that a JPA entity is extensible and use the @XmlVirtualAccessMethods annotation to specify that a JAXB bean is extensible. In both cases, you use virtual properties to specify external mappings. This allows you to modify the mappings without modifying source files and without redeploying the persistence unit.

For information on how to make JPA entities and JAXB beans extensible, see "Making JPA Entities and JAXB Beans Extensible" in Solutions Guide for Oracle TopLink.