Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g (10.1.3.5.0) Part Number E13981-01 |
|
|
View PDF |
Every JPA entity must have a primary key.
You can specify a primary key as a single primitive, or JDK object type entity field (see "Configuring a JPA Entity Simple Primary Key Field").
You can specify a composite primary key made up of one or more primitive, or JDK object types using a separate composite primary key class (see "Configuring a JPA Entity Composite Primary Key Class").
You can either assign primary key values yourself, or you can associate a primary key field with a primary key value generator (see "Configuring JPA Entity Automatic Primary Key Generation").
The simplest primary key is one you specify as a single primitive or JDK object type entity field (see "Using Annotations").
Note:
For a JPA entity primary key field code example, see:http://www.oracle.com/technology/tech/java/oc4j/ejb3/howtos-ejb3/howtoejb30mappingannotations/doc/how-to-ejb30-mapping-annotations.html#id
Example 7-1 shows how to use the @Id
annotation to specify an entity field as the primary key. In this example, primary key values are generated using a table generator (see "Configuring JPA Entity Automatic Primary Key Generation").
A composite primary key is usually made up of two or more primitive or JDK object types. Composite primary keys typically arise when mapping from legacy databases when the database key is comprised of several columns. You can specify such a composite primary key with a separate composite primary key class (see "Using Annotations")
A composite primary key class has the following characteristics:
It is a POJO class.
It must be public and must have a public no-argument constructor.
If you use property-based access, the properties of the primary key class must be public or protected.
It must be serializable.
It must define equals
and hashCode
methods.
The semantics of value equality for these methods must be consistent with the database equality for the database types to which the key is mapped.
You can make the composite primary key class either an embedded class owned by the entity class, or a nonembedded class whose fields you map to multiple fields or properties of the entity class. In the latter case, the names of primary key fields or properties in the composite primary key class and those of the entity class must correspond and their types must be the same.
Example 7-2 shows a typical embeddable composite primary key class. Example 7-3 shows how to configure a JPA entity with this embedded composite primary key class using the @EmbeddedId
annotation.
Example 7-2 Embeddable Composite Primary Key Class
@Embeddable public class EmployeePK implements Serializable { private String name; private long id; public EmployeePK() { } public String getName() { return name; } public void setName(String name) { this.name = name; } public long getId() { return id; } public void setId(long id) { this.id = id; } public int hashCode() { return (int) name.hashCode() + id; } public boolean equals(Object obj) { if (obj == this) return true; if (!(obj instanceof EmployeePK)) return false; if (obj == null) return false; EmployeePK pk = (EmployeePK) obj; return pk.id == id && pk.name.equals(name); } }
Example 7-3 JPA Entity With an Embedded Composite Primary Key Class
@Entity public class Employee implements Serializable { EmployeePK primaryKey; public Employee() { } @EmbeddedId public EmployeePK getPrimaryKey() { return primaryKey; } public void setPrimaryKey(EmployeePK pk) { primaryKey = pk; } ... }
Example 7-5 shows a nonembedded composite primary key class. In this class, fields empName
and birthDay
must correspond in name and type to properties in the entity class. Example 7-5 shows how to configure a JPA entity with this nonembedded composite primary key class using the @IdClass
annotation. Because entity class fields empName
and birthDay
are used in the primary key, you must also annotate them using the @Id
annotation.
Example 7-4 Non-Embedded Composite Primary Key Class
public class EmployeePK implements Serializable { private String empName; private Date birthDay; public EmployeePK() { } public String getName() { return empName; } public void setName(String name) { empName = name; } public long getDateOfBirth() { return birthDay; } public void setDateOfBirth(Date date) { birthDay = date; } public int hashCode() { return (int) empName.hashCode(); } public boolean equals(Object obj) { if (obj == this) return true; if (!(obj instanceof EmployeePK)) return false; if (obj == null) return false; EmployeePK pk = (EmployeePK) obj; return pk.birthDay == birthDay && pk.empName.equals(empName); } }
Typically, you associate a primary key field (see "Configuring a JPA Entity Simple Primary Key Field") with a primary key value generator so that when an entity instance is created, a new, unique primary key value is assigned automatically.
Table 7-2 lists the types of primary key value generators that you can define.
Table 7-2 JPA Entity Primary Key Value Generators
Type | Description | For more information, see ... |
---|---|---|
Generated Id Table |
A database table that the container uses to store generated primary key values for entities. Typically shared by multiple entity types that use table-based primary key generation. Each entity type will typically use its own row in the table to generate the primary key values for that entity class. Primary key values are positive integers. |
"Table Sequencing" in the Oracle TopLink Developer's Guide |
Table Generator |
A primary key generator, which you can reference by name, defined at one of the package, class, method, or field level. The level at which you define it will depend upon the desired visibility and sharing of the generator. No scoping or visibility rules are actually enforced. Oracle recommends that you define the generator at the level for which it will be used. This generator is based on a database table. |
"Table Sequencing" in the Oracle TopLink Developer's Guide |
Sequence Generator |
A primary key generator which you can reference by name, defined at one of the package, class, method, or field level. The level, at which you define it, will depend upon the desired visibility and sharing of the generator. No scoping or visibility rules are actually enforced. Oracle recommends that you define the generator at the level for which it will be used. This generator is based on a sequence object that the database server provides. |
"Native Sequencing With an Oracle Database Platform" in the Oracle TopLink Developer's Guide "Native Sequencing With a Non-Oracle Database Platform" in the Oracle TopLink Developer's Guide |
Note:
For an EJB 3.0 automatic primary key generation code example, see:http://www.oracle.com/technology/tech/java/oc4j/ejb3/howtos-ejb3/howtoejb30mappingannotations/doc/how-to-ejb30-mapping-annotations.html#sequencing
Example 7-6 shows how to use the @TableGenerator
annotation to specify a primary key value generator based on a database table. The TopLink JPA persistence provider will attempt to create this table at deployment time: if it cannot, then you must follow your database documentation to ensure that this table exists before deployment. When a new instance of Address
is created, a new value for entity field id
is obtained from ADDRESS_GENERATOR_TABLE
. In this case, you must set the @GeneratedValue
annotation attribute strategy
to TABLE
and generator
to ADDRESS_TABLE_GENERATOR
.
Example 7-6 GeneratedValue Strategy Table: @TableGenerator
@Entity @Table(name="EJB_ADDRESS") public class Address implements Serializable { ... @TableGenerator( name="ADDRESS_TABLE_GENERATOR", tableName="ADDRESS_GENERATOR_TABLE", pkColumnValue="ADDRESS_SEQ" ) @Id @GeneratedValue(strategy="TABLE", generator="ADDRESS_TABLE_GENERATOR") @Column(name="ADDRESS_ID") public Integer getId() { return id; } ... }
Example 7-7 shows how to use the @SequenceGenerator
annotation to specify a primary key value generator based on a sequence object provided by the database. The TopLink JPA persistence provider will attempt to create this object at deployment time: if it cannot, then you must follow your database documentation to ensure that this sequence object exists before deployment. When a new instance of Address
is created, a new value for entity field id
is obtained from database sequence object ADDRESS_SEQ
. In this case, you must set the @GeneratedValue
annotation attribute strategy
to SEQUENCE
and generator
to ADDRESS_SEQUENCE_GENERATOR
.
Example 7-7 GeneratedValue Strategy Sequence: @SequenceGenerator
@Entity @Table(name="EJB_ADDRESS") public class Address implements Serializable { ... @SequenceGenerator( name="ADDRESS_SEQUENCE_GENERATOR", sequenceName="ADDRESS_SEQ" ) @Id @GeneratedValue(strategy="SEQUENCE", generator="ADDRESS_SEQUENCE_GENERATOR") @Column(name="ADDRESS_ID") public Integer getId() { return id; } ... }
Example 7-8 shows how to use the @GeneratedValue
annotation to specify a primary key value generator based on a primary key identity column (autonumber column). When a new instance of Address
is persisted, the database assigns a value to the identity column. In this case, the TopLink JPA persistence provider re-reads the inserted row and updates the in-memory Address
entity to set id
to this value.