The JPA specification requires you to declare one or more identity fields in your persistent classes. OpenJPA fully supports this form of object identity, called application identity. OpenJPA, however, also supports datastore identity. In datastore identity, you do not declare any primary key fields. OpenJPA manages the identity of your persistent objects for you through a surrogate key in the database.

You can control how your JPA datastore identity value is generated through OpenJPA's org.apache.openjpa.persistence.DataStoreId class annotation. This annotation has strategy and generator properties that mirror the same-named properties on the standard javax.persistence.GeneratedValue annotation described in Section 2.2, “ Id ” of the JPA Overview.

To retrieve the identity value of a datastore identity entity, use the OpenJPAEntityManager.getObjectId(Object entity) method. See Section 2.2, “ OpenJPAEntityManager ” for more information on the OpenJPAEntityManager.

import org.apache.openjpa.persistence.*;

@Entity
@DataStoreId
public class LineItem {

    ... no @Id fields declared ...
}

Internally, OpenJPA uses the public org.apache.openjpa.util.Id class for datastore identity objects. When writing OpenJPA plugins, you can manipulate datastore identity objects by casting them to this class. You can also create your own Id instances and pass them to any internal OpenJPA method that expects an identity object.

In JPA, you will never see Id instances directly. Instead, calling OpenJPAEntityManager.getObjectId on a datastore identity object will return the Long surrogate primary key value for that object. You can then use this value in calls to EntityManager.find for subsequent lookups of the same record.

The JPA specification limits identity fields to simple types. OpenJPA, however, also allows ManyToOne and OneToOne relations to be identity fields. To identify a relation field as an identity field, simply annotate it with both the @ManyToOne or @OneToOne relation annotation and the @Id identity annotation.

When finding an entity identified by a relation, pass the id of the relation to the EntityManager.find method:

public Delivery createDelivery(Order order) {
    Delivery delivery = new Delivery();
    delivery.setId(order);
    delivery.setDelivered(new Date());
    return delivery;
}

public Delivery findDelivery(EntityManager em, Order order) {
    // use the identity of the related instance 
    return em.find(Delivery.class, order.getId());
}

When your entity has multiple identity fields, at least one of which is a relation to another entity, you must use an identity class (see Section 2.1, “ Identity Class ” in the JPA Overview). You cannot use an embedded identity object. Identity class fields corresponding to entity identity fields should be of the same type as the related entity's identity.

@Entity
public class Order {

    @Id
    private long id;

    ... 
}

@Entity
@IdClass(LineItemId.class)
public class LineItem {
    
    @Id
    private int index;

    @Id
    @ManyToOne
    private Order order;

    ...
}

public class LineItemId {

    public int index;
    public long order; // same type as order's identity

    ...
}

In the example above, if Order had used an identity class OrderId in place of a simple long value, then the LineItemId.order field would have been of type OrderId.

If you choose to use application identity, you may want to take advantage of OpenJPA's application identity tool. The application identity tool generates Java code implementing the identity class for any persistent type using application identity. The code satisfies all the requirements the specification places on identity classes. You can use it as-is, or simply use it as a starting point, editing it to meet your needs.

Before you can run the application identity tool on a persistent class, the class must be compiled and must have complete metadata. All primary key fields must be marked as such in the metadata.

In JPA metadata, do not attempt to specify the @IdClass annotation unless you are using the application identity tool to overwrite an existing identity class. Attempting to set the value of the @IdClass to a non-existent class will prevent your persistent class from compiling. Instead, use the -name or -suffix options described below to tell OpenJPA what name to give your generated identity class. Once the application identity tool has generated the class code, you can set the @IdClass annotation.

The application identity tool can be invoked via its Java class, org.apache.openjpa.enhance.ApplicationIdTool.

java org.apache.openjpa.enhance.ApplicationIdTool -s Id Magazine.java

The application identity tool accepts the standard set of command-line arguments defined by the configuration framework (see Section 3, “ Command Line Configuration ”), including code formatting flags described in Section 3.1, “ Code Formatting ”. It also accepts the following arguments:

Each additional argument to the tool must be one of the following:

If you do not supply any arguments to the tool, it will act on the classes in your persistent classes list (see Section 1, “ Persistent Class List ”).

Section 2.3, “ Generated Value ” explains how to use JPA's IDENTITY generation type to automatically assign field values. However, here are some additional caveats you should be aware of when using IDENTITY generation: