Any application defined object with the following characteristics can be an Entity:

• It can be made persistent
• It has a persistent identity (i.e. a unique key)
• It is not a primitive, a primitive wrapper of build-in object.

So in most cases a concrete or an abstract class can be an Entity.

Mixed inheritance is supported - the superclass and/or subclass of an Entity does not have to be an Entity.

All Entities must have a persistent id (i.e. a database primary key). This is known as the entity identity (or persistence identity) JPA supports

• Single field identity (like our long uidPk field)
• Composite primary keys (provided by an Identity class)

The Entity Identity must be defined on the root Entity or mapped superclass of the hierarchy. In our domain model, we have the uidPk identity defined on the Persistable interface. Persistence classes need to implement the getUidPk() method with the @Id annotation and setUidPk() method.

JPA supports several strategies for primary key generation:

• Auto - leave the decision up to the JPA implementation.
• Identity - the database will assign an identity value on insert
• Sequence - use a datastore sequence to generate a value
• Table - use a sequence table to generate a field value

Table is the generator used in our object model, as this will work with all databases, and offers the best overall performance. In our persistence classes we define the generator table JPA_GENERATED_KEYS with columns ID and LAST_VALUE, with a name and primary key value matching the name of the DB table that the class will be persisted to. JPA uses this table to keep track of the last identifier value used to ensure the next one used is unique. You can configure the number of values to allocate in memory for each trip to the database (default is 50). Allocating values in memory allows the JPA runtime to avoid accessing the database for every sequence request.

The annotations on the getUidPk() method are as follows:

@Id
@Column(name = "UIDPK")
@GeneratedValue(strategy = GenerationType.TABLE, generator = TABLE_NAME)
@TableGenerator(name = TABLE_NAME, table = "JPA_GENERATED_KEYS",
                pkColumnName = "ID", valueColumnName = "LAST_VALUE", pkColumnValue = TABLE_NAME)

Most annotations are placed directly into the class files of the objects to be persisted. This makes it easy to maintain consistency between the objects and their persistence definition - there is no need to go find the "mapping file". Annotations are generally quicker to type than XML mapping definitions and IDE's like Eclipse support annotations including syntax checking and auto-completion. The exception to the rule is annotations that define named queries (see below).

Annotations can be at the field level (persistence layer writes directly to the field) or at the property level (persistence layer uses the getter and setter). You cannot mix field level and property level annotations within the same class hierarchy.

As a standard our object model uses property level annotations. So the annotations in the class files are written above the getter method for each property.

Here's a list of some of the more common simple annotations:

Note that properties in a class defined as an Entity that do not have any annotations may still be treated as persistable depending on the type. To avoid any confusion, ensure you annotate all property getters including @Basic and @Transient properties!

Here's a list of some of the annotations commonly used for mapping relationships in JPA

JPA provides two annotations for supporting inheritance

OpenJPA provides some useful annotations in addition to those provided by the JPA specs. Many of these were required in our system due to the complexity of the object domain model. An overview of the OpenJPA specific annotations commonly used are as follows:

Here is an example of an annotated class file which shows many of the annotation types in use

@Entity
@Table(name = "TPRODUCT")
public class ProductImpl extends AbstractEntityImpl implements Product {

  ...

  @Basic
  @Column(name = "START_DATE")
  public Date getStartDate() {
    return this.startDate;
  }

  @Version
  @Column(name = "LAST_MODIFIED_DATE")
  @Temporal(TemporalType.TIMESTAMP)
  public Date getLastModifiedDate() {
    return lastModifiedDate;
  }

  @ManyToOne(targetEntity = ProductTypeImpl.class)
  @JoinColumn(name = "PRODUCT_TYPE_UID")
  public ProductType getProductType() {
    return this.productType;
  }

  @Transient
  public ProductSku getDefaultSku() {
    if (defaultSku == null && productSkus != null && productSkus.size() > 0) {
      return (ProductSku) productSkus.values().iterator().next();
    }
    return defaultSku;
  }

  @OneToMany(targetEntity = ProductPriceImpl.class,
             cascade = { CascadeType.PERSIST, CascadeType.REMOVE })
  @MapKey(name = "currencyCode")
  @ElementJoinColumn(name = "PRODUCT_UID")
  public Map getProductPrices() {
    return productPrices;
  }

  ...

}

JPQL executes over the abstract persistence schema (the entities you've created) defined by your persistence unit, rather than over the database like traditional SQL.

JPQL supports a SQL like syntax

SELECT [PD:<result>]
    [PD:FROM <candidate-class(es)>]
    [PD:WHERE <filter>]
    [PD:GROUP BY <grouping>]
    [PD:HAVING <having>]
    [PD:ORDER BY <ordering>]

JPQL supports dynamic and static (named) queries

A simple query for all CategoryTypeImpl entities

SELECT ct FROM CategoryTypeImpl ct

The optional where clause places criteria on matching results. For example

SELECT j FROM ImportJobImpl j WHERE j.name = '01-SnapItUp'

And of course you can specify parameters, for example

SELECT c FROM CategoryImpl c WHERE c.code = ?1

JPQL queries may specify one or more join fetch declarations, which allow the query to specify which fields in the returned instances will be pre-fetched

SELECT ct FROM CategoryTypeImpl ct JOIN FETCH ct.categoryAttributeGroupAttributes

Multiple fields may be specified in separate join fetch declarations. You may want to use other join types depending on the data, e.g. left outer join fetch.

JPA supports the concept of named queries. While named queries can be defined in the annotations of a class (usually the class in which the named query is most relevant), they can also be defined external to the implementation class source files in XML files. In this case, each Java package has its own named queries XML file in META-INF/, entitled <packagename>-orm.xml. This is useful for keeping all the named queries specific to a package in the same place while allowing easier extensibility, so that queries can be modified without requiring the application to be recompiled.

Here is an example of named queries in an XML file:

<?xml version="1.0" encoding="UTF-8"?>
<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm http://java.sun.com/xml/ns/persistence/orm_1_0.xsd" 
    version="1.0">
    <package>com.elasticpath.domain.customer.impl</package>
    <entity class="CustomerDeletedImpl">
        <named-query name="CUSTOMER_UIDS_SELECT_BY_DELETED_DATE">
            <query>select pd.customerUid from CustomerDeletedImpl as pd where pd.deletedDate &gt;= ?1</query>
        </named-query>
    </entity>
    <entity class="CustomerGroupImpl">
        <named-query name="CUSTOMERGROUP_SELECT_ALL">
            <query>select cg from CustomerGroupImpl cg</query>
        </named-query>
        <named-query name="CUSTOMERGROUP_FIND_BY_NAME">
            <query>select cg from CustomerGroupImpl cg where cg.name = ?1</query>
        </named-query>
    </entity>
</entity-mappings>

One of the key interfaces in the Java Persistence API is the EntityManager. This is similar to Hibernate's Session interface, providing services for CRUD operations (persist, remove, find, merge etc), creating Query instances and interfacing to the Transaction API.

Spring provides JPA integration, implementing JPA Container responsibilities. It includes beans like LocalEntityManagerFactoryBean which make it easy to configure the Entity Manager Factory through Spring configuration files, and SharedEntityManagerBean which provides a shared EntityManager reference.

JPA has been integrated with Elastic Path's core persistence model, which makes considerable use of Spring Inversion of Control and Dependency Injection.

Here is a summary of the core classes that you'll use for persistence. You can find these in the com.elasticpath.persistence.openjpa.impl package of ep-persistence-openjpa

The majority of the time you'll just use the persistence-api PersistenceEngine interface, and configure Spring to inject the JPA implementation, so your code generally doesn't need to know anything about JPA.

JPA does not support the Locale and Currency types so some special OpenJPA annotations are required when using these datatypes.

For example, here are annotated getters for Locale and Currency fields:

@Persistent(optional = false)
  @Externalizer("toString")
  @Factory("org.apache.commons.lang.LocaleUtils.toLocale")
  @Column(name = "LOCALE", length = 20)
  public Locale getLocale() {
    return locale;
  }

  @Persistent
  @Column(name = "CURRENCY", length = 3)
  @Externalizer("getCurrencyCode")
  @Factory("com.elasticpath.commons.util.impl.UtilityImpl.currencyFromString")
  public Currency getCurrency() {
    return currency;
  }

This tells JPA the externalizer method to use to convert the field into its external form for database storage (eg getCurrencyCode()) for Currency), and to the full class and method to instantiate the field from the external form stored in the database.

JPA requires all entities to have a default constructor which it will call when the persistence layer starts up. If there is no default constructor the build-time enhancer will add one for you.

Where you need to be careful is if you have code in your constructor that is expecting other objects to have already been instantiated. For example, this code was originally in the constructor for ShoppingCartImpl

public ShoppingCartImpl() {
  super();
  this.shippingServiceLevelList = new ArrayList();
  this.viewHistory = (ViewHistory) getElasticPath().getBean("viewHistory");
}

Before this class was annotated as a JPA Entity the constructor wasn't being called until the ElasticPathImpl bean factory added a bean for ShoppingCartImpl, so the call to getElasticPath() would always work. However, once this class was added to the list of persistence entities, the constructor was being called before ElasticPathImpl was being instantiated, so the call to getElasticPath() would fail!

The work around is to put any code in the constructor that relies on other objects in a more appropriate place. In this particular case the code to get the viewHistory bean was moved into the getViewHistory method of ShoppingCartImpl.

The mapping tool can generate a schema from your object model. It is very useful for checking if your annotations map the object(s) to the current schema, or for generating the SQL if you add a new object.

You can run the tool by calling the following Maven command in the ep-core directory:

mvn -Dopenjpa.ConnectionDriverName=com.mysql.jdbc.Driver openjpa:sql

The generated file, database.sql, can be found in ep-core\target.