Annotation Interface Entity

@Documented @Target(TYPE) @Retention(RUNTIME) public @interface Entity
Declares that the annotated class is an entity. The annotated entity class must:
  • be a non-final top-level class or static inner class,
  • have a public or protected constructor with no parameters, and
  • have no final methods or persistent instance variables.

An entity might be an abstract class, or it might be a concrete class. An entity may extend a non-entity class, or it may extend another entity class. A non-entity class may extend an entity class.

An enum, record, or interface may not be designated as an entity.

The persistent state of an entity is represented by instance variables, which may correspond to JavaBeans-style properties. An instance variable may be directly accessed only within the methods of the entity, by the entity instance itself. An instance variable of an entity must not be directly accessed by a client of the entity. The state of the entity is available to clients only through the methods of the entity.

The persistent state is accessed by the persistence provider runtime using either:

The entity-level access type determines whether the provider accesses the state of an entity using getter and setter methods or by directly reading and writing its fields. It is almost never necessary to explicitly specify an AccessType, since the default access type for an entity is determined by the placement of mapping annotations on the entity class: if the mapping annotations are placed on getters, property access is assumed; if the mapping annotations are placed on fields, field access is assumed.

The instance variables of a class must have either private, protected, or package visibility, independent of whether field access or property access is used. When property access is used, the property accessor methods must be public or protected.

The declared type of a persistent field or property must not involve a type variable.

An entity has a primary table, mapped using the Table annotation, and may have one or more secondary tables, mapped using the SecondaryTable annotation.

An entity class holds state, represented as persistent fields and properties:

  • a field or property of basic type maps to a single column in one of the tables mapped by the entity,
  • a field or property of embeddable type has nested mappings to multiple columns in one of the tables mapped by the entity,
  • an element collection usually maps to a separate collection table,
  • a many-to-one association usually maps to a foreign key column or columns in one of the tables mapped by the entity,
  • a one-to-one association usually maps to a unique foreign key relationship (sometimes using a shared primary key),
  • a one-to-many association usually maps to a foreign key column or columns in one of the tables mapped by the associated entity, and
  • a many-to-many association usually maps to a join table.

Every entity class must have at least one field or property annotated Id or EmbeddedId holding the primary key of the entity. An entity class may optionally have a field or property annotated Version, which holds a value used to detect optimistic locking conflicts.

Fields or properties of an entity class are persistent by default. The Transient annotation or the Java transient keyword must be used to explicitly declare any field or property of an entity which is not persistent.

A field or property of an entity instance might be fetched eagerly when the entity is loaded from the database, or it might be fetched lazily from the database, either:

  • transparently on first access, if the entity is a managed instance belonging to a persistence context, or
  • by calling the method EntityAgent.fetch(T), if the entity is detached and not associated with any persistence context.

By default:

  • fields or properties of basic or embedded type, one-to-one associations, and many-to-one associations are fetched eagerly, but
  • element collections, one-to-many associations, and many-to-many associations are fetched lazily.

Lazy fetching may be controlled using the fetch member of the mapping annotations Basic, OneToOne, ManyToOne, OneToMany, and ManyToMany, or by an EntityGraph. However, lazy fetching is always a hint, and the persistence provider is always permitted to fetch more data than what is explicitly requested by the application or required by the Persistence specification.

By default, a field or property of non-primitive basic type, a one-to-one association, or a many-to-one association is assumed to be optional, that is, it may hold a null value when the state of the entity is written to the database. A field or property is non-optional if:

  • the field or property has a primitive type,
  • the field or property is annotated jakarta.annotation.Nonnull, or
  • the field or property has a Basic, OneToOne, or ManyToOne annotation specifying optional=false.

Apart from its persistent fields and properties, an entity class may declare callback methods using:

Alternatively, the entity class may specify any number of entity listener classes which declare callback methods and are notified of lifecycle events relating to the entity.

Since:
1.0

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    name
    (Optional) The entity name.

  • Element Details

    • name

      String name
      (Optional) The entity name. Defaults to the unqualified name of the entity class. This name is used to refer to the entity in queries. The name must be a legal Java identifier, and must not be a reserved identifier in the Jakarta Persistence query language.
      Default:
      ""