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

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 >

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

@GeneratedValue@SequenceGenerator@TableGenerator

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.

JPA and NoSQL

The Java Persistence specification is an API (JPA) for creating, removing and querying across lightweight Java objects and can be used both within a compliant EJB 3.0 Container and a standard Java SE 5 environment. Oracle TopLink is a leader in the JPA community delivering the JPA 1.0, 2.0, and 2.1 reference implementations and now having developed the JPA 2.0 reference implementation with EclipseLink.

Starting with Oracle TopLink 12.1.2 developers can now access NoSQL data through TopLink's NoSQL mapping and persistence API.

Resources

Java Persistence API (JPA) and TopLink JPA.

Valuable resources for developers using the Java Persistence API (JPA) and TopLink JPA.

Pro EJB 3 - Java Persistence API

The first JPA book available by Oracle's own Mike Keith and Merrick Schincariol.

Technical Information

  • TopLink JPA Extensions Reference A description of the extensions offered by the TopLink implementation. These include query hints and Persistence.XML property flags.
  • The Project GlassFish website has a number of articles and blogs on using TopLink Essentials both inside the GlassFish application server and in Java SE applications.
Tutorials

JPA in a Web Container

How to use JPA in Java SE

Testing EJB's that use JPA outside the Container Coming Soon

Building Java SE Applications using JPA Coming Soon

TopLink JPA: How-To's

These JPA How-To's focus on providing developers with a brief explanation and sample code to accomplish common development tasks. The goal is to provide a resource that developers can quickly reference and use.

TopLink JPA: Examples

Complete working examples of applications illustrating various Java Persistence API (JPA) supported architectures and functionality.

JPA in JSF Web Application

An example illustrating basic JPA mapping, querying, and entity lifecycle management in a Java Server Faces Web application.

JPA in EJB 3.0 Container

SRDemo: This is an update to the Service Request Demo provided with the 10.1.3.0 release. The version migrates the persistence from proprietary TopLink to TopLink JPA using annotations for all mappings and entity configuration. 
Coming Soon