Home | Download | PDF | API | FAQ | Search | Feedback | History

> ## 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 that 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.

> ### Requirements for Entity Classes

> An entity class must follow these requirements:

> - The class must be annotated with the `javax.persistence.Entity` annotation.
> - The class must have a public or protected, no-argument constructor. The class may have other constructors.
> - The class must not be declared `final`. No methods or persistent instance variables must be declared `final`.
> - If an entity instance be passed by value as a detached object, such as through a session bean's remote business interface, the class must implement the `Serializable` interface.
> - Entities may extend both entity and non-entity classes, and non-entity classes may extend entity classes.
> - Persistent instance variables must be declared private, protected, or package-private, and can only be accessed directly by the entity class's methods. Clients should access the entity's state through accessor or business methods.

> ### Persistent Fields and Properties in Entity Classes

> The persistent state of an entity can be accessed either through the entity's instance variables or through JavaBeans-style properties. The fields or properties must be of the following Java language types:

> - Java primitive types
> - `java.lang.String`
> - other serializable types including:
> - wrappers of Java primitive types
> - `java.math.BigInteger`
> - `java.math.BigDecimal`
> - `java.util.Date`
> - `java.util.Calendar`
> - `java.sql.Date`
> - `java.sql.Time`
> - `java.sql.TimeStamp`
> - user-defined serializable types
> - `byte[]`
> - `Byte[]`
> - `char[]`
> - `Character[]`
> - enumerated types
> - other entities and/or collections of entities
> - embeddable classes

> #### Persistent Fields

> If the entity class uses persistent fields, the Persistence runtime accesses entity class instance variables directly. All fields not annotated `javax.persistence.Transient` will be persisted to the data store. The object/relational mapping annotations must be applied to the instance variables.

> #### Persistent Properties

> If the entity uses persistent properties, the entity must follow the method conventions of JavaBeans components. JavaBeans-style properties use getter and setter methods that are named after the entity class's instance variable names. For every persistent property `property` of type `Type` of the entity, there is a getter method `get` `Property` and setter method `set` `Property`. If property is a boolean, you may use `is` `Property` instead of `get` `Property`. For example, if a `Customer` entity uses persistent properties, and has a private instance variable called `firstName`, the class defines a `getFirstName` and `setFirstName` method for retrieving and setting the state of the `firstName` instance variable.

> The method signature for single-valued persistent properties are as follows:

>     Type getProperty()
>     void setProperty(Type type)

> Collection-valued persistent fields and properties must use the `java.util.Collection` interfaces regardless of whether the entity uses persistent fields or properties. The following collection interfaces may be used:

> - `java.util.Collection`
> - `java.util.Set`
> - `java.util.List`
> - `java.util.Map`

> If the entity class uses persistent fields, the type in the above method signatures must be one of these collection types. Generic variants of these collection types may also be used. For example, if the `Customer` entity has a persistent property that contains a set of phone numbers, it would have the following methods:

>     Set<PhoneNumber> getPhoneNumbers() {}
>     void setPhoneNumbers(Set<PhoneNumber>) {}

> The object/relational mapping annotations for must be applied to the getter methods. Mapping annotations cannot be applied to fields or properties annotated `@Transient`.

> ### Primary Keys in Entities

> Each entity has a unique object identifier. A customer entity, for example, might be identified by a customer number. The unique identifier, or primary key, enables clients to locate a particular entity instance. Every entity must have a primary key. An entity may have either a simple or a composite primary key.

> Simple primary keys use the `javax.persistence.Id` annotation to denote the primary key property or field.

> Composite primary keys must correspond to either a single persistent property or field, or to a set of single persistent properties or fields. Composite primary keys must be defined in a primary key class. Composite primary keys are denoted using the `javax.persistence.EmbeddedId` and `javax.persistence.IdClass` annotations.

> The primary key, or the property or field of a composite primary key, must be one of the following Java language types:

> - Java primitive types
> - Java primitive wrapper types
> - `java.lang.String`
> - `java.util.Date` (the temporal type should be `DATE`)
> - `java.sql.Date`

> Floating point types should never be used in primary keys. If you use a generated primary key, only integral types will be portable.

> #### Primary Key Classes

> A primary key class must meet these requirements:

> - The access control modifier of the class must be `public`.
> - The properties of the primary key class must be `public` or `protected` if property-based access is used.
> - The class must have a public default constructor.
> - The class must implement the `hashCode()` and `equals(Object other)` methods.
> - The class must be serializable.
> - A composite primary key must be represented and mapped to multiple fields or properties of the entity class, or must be represented and mapped as an embeddable class.
> - If the class is mapped to multiple fields or properties of the entity class, the names and types of the primary key fields or properties in the primary key class must match those of the entity class.

> The following primary key class is a composite key, the `orderId` and `itemId` fields together uniquely identify an entity.

>     public final class LineItemKey implements Serializable {
>       public Integer orderId;
>       public int itemId;

>       public LineItemKey() {}

>       public LineItemKey(Integer orderId, int itemId) {
>         this.orderId = orderId;
>         this.itemId = itemId;
>       }

>       public boolean equals(Object otherOb) {
>         if (this == otherOb) {
>           return true;
>         }
>         if (!(otherOb instanceof LineItemKey)) {
>           return false;
>         }
>         LineItemKey other = (LineItemKey) otherOb;
>         return (
>               (orderId==null?other.orderId==null:orderId.equals
>               (other.orderId)
>               )
>               &&
>               (itemId == other.itemId)
>             );
>       }

>       public int hashCode() {
>         return (
>               (orderId==null?0:orderId.hashCode())
>               ^
>               ((int) itemId)
>             );
>       }

>       public String toString() {
>         return "" + orderId + "-" + itemId;
>       }
>     }

> ### Multiplicity in Entity Relationships

> There are four types of multiplicities: one-to-one, one-to-many, many-to-one, and many-to-many.

> One-to-one: Each entity instance is related to a single instance of another entity. For example, to model a physical warehouse in which each storage bin contains a single widget, `StorageBin` and `Widget` would have a one-to-one relationship. One-to-one relationships use the `javax.persistence.OneToOne` annotation on the corresponding persistent property or field.

> One-to-many: An entity instance can be related to multiple instances of the other entities. A sales order, for example, can have multiple line items. In the order application, `Order` would have a one-to-many relationship with `LineItem`. One-to-many relationships use the `javax.persistence.OneToMany` annotation on the corresponding persistent property or field.

> Many-to-one: Multiple instances of an entity can be related to a single instance of the other entity. This multiplicity is the opposite of a one-to-many relationship. In the example just mentioned, from the perspective of `LineItem` the relationship to `Order` is many-to-one. Many-to-one relationships use the `javax.persistence.ManyToOne` annotation on the corresponding persistent property or field.

> Many-to-many: The entity instances can be related to multiple instances of each other. For example, in college each course has many students, and every student may take several courses. Therefore, in an enrollment application, `Course` and `Student` would have a many-to-many relationship. Many-to-many relationships use the `javax.persistence.ManyToMany` annotation on the corresponding persistent property or field.

> ### Direction in Entity Relationships

> The direction of a relationship can be either bidirectional or unidirectional. A bidirectional relationship has both an owning side and an inverse side. A unidirectional relationship has only an owning side. The owning side of a relationship determines how the Persistence runtime makes updates to the relationship in the database.

> #### Bidirectional Relationships

> In a bidirectional relationship, each entity has a relationship field or property that refers to the other entity. Through the relationship field or property, an entity class's code can access its related object. If an entity has a relative field, then we often say that it "knows" about its related object. For example, if `Order` knows what `LineItem` instances it has and if `LineItem` knows what `Order` it belongs to, then they have a bidirectional relationship.

> Bidirectional relationships must follow these rules:

> - The inverse side of a bidirectional relationship must refer to its owning side by using the `mappedBy` element of the `@OneToOne`, `@OneToMany`, or `@ManyToMany` annotation. The `mappedBy` element designates the property or field in the entity that is the owner of the relationship.
> - The many side of many-to-many and many-to-one bidirectional relationships must not define the `mappedBy` element. The many side is always the owning side of the relationship.
> - For one-to-one bidirectional relationships, the owning side corresponds to the side that contains the corresponding foreign key.
> - For many-to-many bidirectional relationships either side may be the owning side.

> #### Unidirectional Relationships

> In a unidirectional relationship, only one entity has a relationship field or property that refers to the other. For example, `LineItem` would have a relationship field that identifies `Product`, but `Product` would not have a relationship field or property for `LineItem`. In other words, `LineItem` knows about `Product`, but `Product` doesn't know which `LineItem` instances refer to it.

> #### Queries and Relationship Direction

> Java Persistence query language queries often navigate across relationships. The direction of a relationship determines whether a query can navigate from one entity to another. For example, a query can navigate from `LineItem` to `Product` but cannot navigate in the opposite direction. For `Order` and `LineItem`, a query could navigate in both directions, because these two entities have a bidirectional relationship.

> #### Cascade Deletes and Relationships

> Entities that use relationships often have dependencies on the existence of the other entity in the relationship. For example, a line item is part of an order, and if the order is deleted, then the line item should also be deleted. This is called a cascade delete relationship.

> Cascade delete relationships are specified using the `cascade=REMOVE` element specification for `@OneToOne` and `@OneToMany` relationships. For example:

>     @OneToMany(cascade=REMOVE, mappedBy="customer")
>     public Set<Order> getOrders() { return orders; }