TopLink JPA: How to Configure Primary Key Generation

Version: 5/12/06

Introduction
Using Sequence Objects
Using Identity Columns
Using a Table
Using a Default Generation Strategy
Summary

Introduction

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

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), you can configure JPA to use a database sequence object to automatically generate identifiers for your persistent objects.

Using A Default Sequence

TopLink JPA 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. TopLink will create a default sequence object during schema generation. This object will be used by TopLink 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 that you are using.

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 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 enable generation of 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. It is completely portable across databases and will be automatically generated for you when schema generation is enabled.

Using A Default Table

During schema generation, TopLink 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. TopLink will create a default table during schema generation. This table will be used by TopLink 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. The 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

ID_NAME ID_VAL

INV_GEN

<last generated value >

ID_NAME	ID_VAL
INV_GEN	<last generated value >

Using a Default Generation Strategy

By specifying a strategy of AUTO you are indicating your intention to let TopLink pick the strategy to use. Typically, TopLink picks TABLE as the strategy, since it is the most portable strategy available (it does not lock you into a particular database). 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;

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.