Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Creating and Configuring Entities"

m
 
(29 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{EclipseLink_UserGuide
 
{{EclipseLink_UserGuide
 
|info=y
 
|info=y
|toc=n
+
|toc=y
 
|eclipselink=y
 
|eclipselink=y
 
|eclipselinktype=JPA
 
|eclipselinktype=JPA
Line 7: Line 7:
 
|apis=
 
|apis=
 
*[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Entity.html @Entity]
 
*[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Entity.html @Entity]
 +
* [http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Id.html @Id]
 
* [http://www.eclipse.org/eclipselink/api/latest/javax/persistence/IdClass.html @IdClass]
 
* [http://www.eclipse.org/eclipselink/api/latest/javax/persistence/IdClass.html @IdClass]
* [http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Embedded.html @Embedded]
+
* [http://www.eclipse.org/eclipselink/api/latest/javax/persistence/package-summary.html Package javax.persistence]
* [http://www.eclipse.org/eclipselink/api/latest/javax/persistence/GeneratedValue.html @GeneratedValue]
+
|nativeapi=y
* [http://www.eclipse.org/eclipselink/api/latest/javax/persistence/TableGenerator.html @TableGenerator]
+
|nativeapis=
* [http://www.eclipse.org/eclipselink/api/latest/javax/persistence/SequenceGenerator.html @SequenceGenerator ]
+
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/descriptors/ClassDescriptor.html ClassDescriptor]}}
* [http://www.eclipse.org/eclipselink/api/latest/javax/persistence/package-summary.html Package javax.persistence]}}
+
 
 +
 
 +
'''[[Image:Elug_draft_icon.png|Warning]] See "Understanding Entities" in the [http://www.eclipse.org/eclipselink/documentation/ EclipseLink Concepts Guide]'''
  
 
= Configuring Entities=
 
= Configuring Entities=
Line 29: Line 32:
 
}
 
}
 
</source>  
 
</source>  
 +
 +
{{EclipseLink_Note|note=The entity class must also be listed in your <tt>persistence.xml</tt> file, unless you set the tag <code><exclude-unlisted-classes></code> to <code>false</code>.  An entity can also be defined using an <tt>orm.xml</tt> file and the <code><entity></code> tag.}}
  
 
{{EclipseLink_Spec
 
{{EclipseLink_Spec
Line 41: Line 46:
 
You can generate and/or configure the identity of your entities by using the following annotations:  
 
You can generate and/or configure the identity of your entities by using the following annotations:  
  
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entities/Ids/Id|@Id]]  
+
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/Id|@Id]]  
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entities/Ids/IdClass|@IdClass]]  
+
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/IdClass|@IdClass]]  
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entities/Ids/EmbeddedId|@EmbeddedId]]  
+
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/EmbeddedId|@EmbeddedId]]  
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entities/Ids/GeneratedValue|@GeneratedValue]]  
+
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/GeneratedValue|@GeneratedValue]]  
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entities/Ids/TableGenerator|@TableGenerator]]  
+
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/TableGenerator|@TableGenerator]]  
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entities/Ids/SequenceGenerator|@SequenceGenerator ]]
+
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/SequenceGenerator|@SequenceGenerator]]
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/UuidGenerator|@UuidGenerator]]
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/GeneratedValue#Advanced Identity Generation|Advanced Identity Generation]]
  
 
You can also use these annotations to fine-tune how your database maintains the identity of your entities.  
 
You can also use these annotations to fine-tune how your database maintains the identity of your entities.  
  
<br>  
+
{{EclipseLink_Note|note=If your class does not have a logical Id then you need to add a generated one.  Embedded objects do not require an Id.}}
 +
<br/>
  
 +
==Configuring an Entity's Table==
 +
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:
 +
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Table|@Table]]
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/SecondaryTable|@SecondaryTable]]
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/SecondaryTable#Advanced Multiple Table Configuration|Advanced Multiple Table Configuration]]
 +
 +
For information on how to create the tables in the database see, [[EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Schema_Generation|Schema Generation]].
 +
 +
==Configuring Inheritance==
 +
JPA defines several difference methods for persisting objects with inheritance.  The <code>@Inheritance</code> annotation is used in the root class to define <code>SINGLE_TABLE</code>, <code>JOINED</code>, and <code>TABLE_PER_CLASS</code> inheritance.  For abstract classes that define common state or persistence behavior, but have no relationship on the database, the <code>@MappedSuperclass</code> annotation can be used.
 +
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Inheritance|@Inheritance]]
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/MappedSuperclass|@MappedSuperclass]]
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Inheritance#Advanced Inheritance Configuration|Advanced Inheritance Configuration]]
 +
 +
==Configuring Embedded Objects==
 +
You can use the <tt>@Embeddable</tt> 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 <tt>@Embedded</tt> annotation for a single reference, <tt>@EmbeddedId</tt> for an embedded id, or the <tt>@ElementCollection</tt> annotation for a <tt>Collection</tt> or <tt>Map</tt> reference.  An embeddable can also be used in any <tt>Map</tt> key using the <tt>@MapKeyClass</tt> annotation.
 +
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Embeddable|@Embeddable]]
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/EmbeddedId|@EmbeddedId]]
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mappings/Embedded|@Embedded]]
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mappings/ElementCollection|@ElementCollection]]
 +
*[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Embeddable#Advanced Embeddable Configuration|Advanced Embeddable Configuration]]
 +
 +
<br>
 
<br>  
 
<br>  
  

Latest revision as of 08:22, 4 April 2013

EclipseLink JPA


Warning See "Understanding Entities" in the EclipseLink Concepts Guide

Configuring 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.

Identifying an Entity

Use the @Entity annotation to specify that a class is an entity, as shown in the following example:

@Entity
public class Employee implements Serializable {
...
}

Elug note icon.png

Note: The entity class must also be listed in your persistence.xml file, unless you set the tag <exclude-unlisted-classes> to false. An entity can also be defined using an orm.xml file and the <entity> tag.

Elug javaspec icon.gif

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

Configuring an Entity's 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:

You can also use these annotations to fine-tune how your database maintains the identity of your entities.

Elug note icon.png

Note: If your class does not have a logical Id then you need to add a generated one. Embedded objects do not require an Id.


Configuring an Entity's Table

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:

For information on how to create the tables in the database see, Schema Generation.

Configuring 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.

Configuring 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.



Eclipselink-logo.gif
Version: 2.2.0 DRAFT
Other versions...