Skip Headers
Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide
10g (10.1.3.1.0)

Part Number B28221-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

Configuring a JPA Entity Primary Key

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").

Configuring a JPA Entity Simple Primary Key Field

The simplest primary key is one you specify as a single primitive or JDK object type entity field (see "Using Annotations").

Using Annotations

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").

Example 7-1 Primary Key Using @Id

@Id(generate=TABLE, generator="ADDRESS_TABLE_GENERATOR")
@TableGenerator(
    name="ADDRESS_TABLE_GENERATOR", 
    tableName="EMPLOYEE_GENERATOR_TABLE", 
    pkColumnValue="ADDRESS_SEQ"
)
@Column(name="ADDRESS_ID")
public Integer getId() {
    return id;
}

Configuring a JPA Entity Composite Primary Key Class

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.

Using Annotations

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);
    }
}

Example 7-5 JPA Entity With a Mapped Composite Primary Key Class

@IdClass(EmployeePK.class)
@Entity
public class Employee {
    @Id String empName;
    @Id Date birthDay;
...
}

Configuring JPA Entity Automatic Primary Key Generation

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


Using Annotations

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.

Example 7-8 @GeneratedValue Strategy Identity

@Entity
@Table(name="EJB_ADDRESS")
public class Address implements Serializable {
...
    @Id @GeneratedValue(strategy="IDENTITY")
    public Integer getId() {
        return id;
    }
...
}