Java Persistence API

The Enterprise Java Beans (EJB) was commonly used in previous versions of HCL Commerce. Starting with Version 9, the Java Persistence API (JPA) will be the standard.

Compatibility with previous versions

EJB was commonly used in previous releases, but from 9.0.0 on, EJB 1.1/2.x support will be deprecated. The APIs that will be supported are JPA, and EJB 3.x. JPA will be the standard technology used for customization of HCL Commerce features.

Existing EJB-based access beans have been replaced by JPA-based Access Beans. Most of the interfaces for these beans are the same as in the previous programming model. For existing 2.x session beans, we provide 3.x session beans using annotation, instead of XML, for configuration. Customizations based on EJB should be migrated to JPA and 3.x session beans.

Guidelines for customizing HCL Commerce using JPA

  • Do not change the default JPA entities, or default database tables.
  • Define custom entity schema.
  • Register custom schema in the keys table. The keys table is used to generate primary keys for custom tables. For example,
    INSERT INTO KEYS VALUES (10002,'xsocialaccount','xsocialaccount_id',10000,500,0,2147483647,0,1048576,1);
    Please refer to the KEYS table for detailed information on each column.
  • Define a custom JPA entity that extends EntityBase. Doing this makes it unnecessary to define optCounter, which is used for optimistic locks. Optionally, JPA entities can implement protected interfaces for access control purposes. You can create a protected interface by extending EntityBase. The access control will be delegated to your access helper class.

    The following code snippet defines a new JPA entity SocialAccount which extends EntityBase. It is mapped to the table "XSOCIALACCOUNT." This new entity has a JPA named query, which defines a JPQL in order to find a social account using member ID.

    @Table(name = "XSOCIALACCOUNT")
            @NamedQuery(name = "SocialAccount.getSocialAccountsByMemberId", query = "select c from SocialAccount c where c.memberId = :memberId") })
    public class SocialAccount extends EntityBase implements Serializable, Protectable {
    The next code snippet defines the attribute with ID annotation, which means that it is mapping to the primary key column XSOCIALACCOUNT_ID in the database table.
    @Column(name = "XSOCIALACCOUNT_ID", nullable = false)
        @Basic(optional = false)
        public Long getSocialAccountId() {
            return socialAccountId;
    The last code snippet below defines an attribute that is mapping to the column STORE_ID in the database table.
    @Column(name = "STORE_ID")
        public Integer getStoreId() {
            return storeId;
  • Define custom DAO implementations that extend AbstractJPAEntityDaoImpl. Implement a constructor using the JPA entity class as the parameter. Doing this allows you to leverage several useful methods, such as basic CRUD, paging, sorting, and generateKey.
    The following code snippet defines a DAO implementation for JPA entity, here is using java generic, SocialAccount is the JPA entity type, and Long is the primary key type.
    public class SocialAccountDaoImpl extends AbstractJPAEntityDaoImpl {   
         * Default constructor.
        public SocialAccountDaoImpl() {
  • Optionally, you can define a custom Access Helper, which extends AccessHelper for access control purpose, where you need to implement getOwner() and fulfill() methods.
  • Store these classes in the WebSphereCommerceServerExtensionsData project. If they cannot be found in this project, your custom JPA entities will not be scanned and loaded.
  • Load an access control policy with the new acpload utility if you need access control.