EclipseLink/Examples/JPA/PrimaryKey

How to Configure Primary Key Generation

This document describes how to configure primary key generation with EclipseLink JPA. See @Generated value in the EclipseLink User's Guide for complete information.

Introduction

EclipseLink may create entity identifiers (or primary keys) automatically using any of the following strategies defined by the JPA Specification:

• Sequence objects
• Identity Columns
• Tables
• Provider-assigned strategy

Usually, these generation strategies are configured locally to the primary key field or property.

Using Sequence Objects

When using a database that supports sequence objects (such as Oracle Database), EclipseLink can use a database sequence object to automatically generate identifiers for your persistent objects.

Using A Default Sequence

EclipseLink can produce a default sequence during schema generation. If you use schema generation, then specify that your identifier should be generated and that the SEQUENCE strategy be used to perform the generation.

In the following example, the @GeneratedValue annotation indicates that the identifier value should be automatically generated; a strategy of SEQUENCE indicates that a database sequence should be used to generate the identifier. EclipseLink will create a default sequence object during schema generation that will be used at run time.

@Entity
public class Inventory implements Serializable {
 
        @Id
        @GeneratedValue(strategy=GenerationType.SEQUENCE)
        private long id;

Specifying a Sequence

To use a specific named sequence object (whether it is generated by schema generation or already exists in the database) you must define a sequence generator using a @SequenceGenerator annotation. You may choose any unique label as the name for the sequence generator. Reference this name by the generator element in the @GeneratedValue annotation. Also, include the sequenceName element to specify the name of the database sequence object to use.

If the sequence object already exists in the database, then you must specify the allocationSize to match the INCREMENT value of the database sequence object. For example, if you have a sequence object in the database that you defined to INCREMENT BY 5, set the allocationSize to 5 in the sequence generator definition, as the following example shows:

@Entity
public class Inventory implements Serializable {
 
        @Id
        @GeneratedValue(generator="InvSeq")
        @SequenceGenerator(name="InvSeq",sequenceName="INV_SEQ", allocationSize=5)
        private long id;

Using Identity Columns

When using a database that does not support sequences, but does support identity columns (such as SQL Server database), you can configure JPA to use an identity column to generate identifiers.

To generate identifiers using identity columns, specify a strategy of IDENTITY. In the following example, the @GeneratedValue annotation indicates that the identifier value should be automatically generated, and the specified strategy of IDENTITY indicates that an identity column should be used to generate the identifier:

@Entity
public class Inventory implements Serializable {
 
        @Id
        @GeneratedValue(strategy=GenerationType.IDENTITY)
        private long id;

Using a Table

You can use a table for identifier generation on any database. This strategy is completely portable across databases and will be automatically generated for you when schema generation is enabled.

Using A Default Table

During schema generation, EclipseLink JPA can generate a default table for identifier generation. If you use schema generation, then specify a strategy of TABLE in the @GeneratedValue annotation, as the following example demonstrates. EclipseLink will create a default table during schema generation that will be used at run time:

@Entity
public class Inventory implements Serializable {
 
        @Id
        @GeneratedValue(strategy=GenerationType.TABLE)
        private long id;

Specifying a Table

To map to an existing table or cause the table object generated by schema generation to be given a particular name, define a table generator using a @TableGenerator annotation.

The table generator has a name, by which it is referenced in the @GeneratedValue annotation. The generator also lists the name of the specific database table, as well as the names of the key and value columns used to store identifier generators in the table. Each row in the table represents the generator for a particular entity type, with the value in the key column indicating the entity type.

For example, a table generator for Inventory instances might have a key of INV_GEN, as the following example shows:

@Entity
public class Inventory implements Serializable {
 
        @Id
        @GeneratedValue(generator="InvTab")
        @TableGenerator(name="InvTab", table="ID_GEN",
            pkColumnName="ID_NAME", valueColumnName="ID_VAL",
            pkColumnValue="INV_GEN")
        private long id;

The table generator defined in the preceding example would be mapped to the following table:

ID_GEN table

ID_NAME	ID_VAL
INV_GEN	<last generated value>

Using a Default Generation Strategy

Specifying a strategy of AUTO allows EclipseLink to select the strategy to use. Typically, EclipseLink picks TABLE as the strategy, since it is the most portable strategy. However, when AUTO is specified, schema generation must be used at least once in order for the default table to be created in the database.

The following example demonstrates the use of the AUTO strategy:

@Entity
public class Inventory implements Serializable {
 
        @Id
        @GeneratedValue(strategy=GenerationType.AUTO)
        private long id;

Using a Custom Strategy

You can also choose to implement your own sequencing. An example using UUID is provided here.

Summary

The minimum configuration you can use to cause the automatic generation of identifiers is to add a @GeneratedValue annotation to the identifier field or property. If you are using a specific named database sequence or table, you need to define the generator in the metadata with @SequenceGenerator or @TableGenerator annotations.

The generation strategy that you choose to generate entity identifiers may depend on the database, on which you application is running: for instance, SEQUENCE and IDENTITY strategies are not supported on all databases.