Extending Domain Model

The Elastic Path Commerce platform is built on a flexible e-commerce domain object model. If your organization has specific needs, you can extend it. Changes to the domain object model affect the platform on many levels, both in terms of functionality and performance. Before making domain changes, you need to carefully consider the impact.

• Be aware of how Load tuners and FetchGroups optimize the loading of fields for different types of objects

• If you are thinking about extending catalog-related domain objects (Product, Catalog, etc.), consider whether you can use attributes instead

The basic steps for extending the domain object model are:

1. Modifying the database schema
2. Creating the domain class and interface
3. Modifying the ORM configuration
4. Add references to the Persistence Unit
5. Registering new domain classes with the BeanRegistrar
6. Enabling bytecode enhancement

Optional steps you may need are:

1. Exclude references from the Persistence Unit
2. Override Persistence Unit Properties

Modifying the database schema

When creating or modifying a domain object, you need to extend the database to store the new data.

If you are creating a completely new domain object, you will need to add a new table.

If you’re extending an existing domain object, we recommended that you use the joined inheritance strategy. With this strategy, the base class’s data is stored in the base table and your extended class’s data is stored in another table. To implement this, you need to:

1. Add a table to store the extension class’s data.

2. Add a discriminator column in the base domain object’s table.

   This discriminator column is used by the persistence layer to identify, for each row, which table contains the row’s extended class’s data field.

Creating the domain class and interface

Any new or extended domain object has both an interface defining the methods and a class containing the implementation. To ensure the domain object’s data is persisted and loaded correctly, the implementation class need to contain the appropriate JPA annotations.

• At the class level, include the following annotations:

  • @Entity and @Table - Identifies the object as an Entity, which is an object that can be persisted in the system.
  • @DiscriminatorValue - Required for an extended domain object. Identifies a value that will be stored in the base table’s discriminator column. The value differentiates the domain objects and the extension objects in their common database table.
  • @DataCache - Extended domain objects do not automatically inherit data cache settings. If the parent class specifies data cache settings, the extended class must also include a matching annotation.

• At the method level, include the following annotations:

  • @Basic and @Column annotations on the getter methods to specify how field data is mapped to table columns.
  • Annotation required to load data from related tables, such as @OneToMany

The following code snippet shows the table annotations for an extension of the OrderImpl class.

@Entity
@Table(name = ExtOrderImpl.TABLE_NAME)
@DiscriminatorValue("extOrder")
@DataCache(enabled = false)
@PrimaryKeyJoinColumn(name="UIDPK", referencedColumnName="UIDPK")
public class ExtOrderImpl extends OrderImpl implements ExtOrder {
    ...
    public static final String TABLE_NAME = "TORDEREXT";

For more information, see the OpenJPA documentation on metadata mapping.

Modifying the ORM (Object Relational Mapping) configuration

If you’re extending an existing domain class, JPA needs to be made aware that the base class accepts extensions. This means overriding the JPA metadata for the base class.

Metadata files are located in core\ep-core\src\main\resources\META-INF.

Add references to the Persistence Unit

New persistence classes and metadata ORM files should be registered in the core extension’s jpa-persistence.xml, which is located in ext-core/src/main/resources/META-INF.

Registering new domain classes with BeanRegister

New domain classes must be registered through the core bean factories. You can add new bean definitions in the core extension’s ep-core-plugin.xml to include entries for the new classes.

After you make this change, running mvn clean install from the command line against the core extension project will compile your classes, perform bytecode enhancement, rebuild the jar, and install it in your repository.

Enabling bytecode enhancement

Most domain classes contain data that needs to be persisted, and all persistent classes need to be bytecode-enhanced. This requires the Maven enhance plugin. Once this is done, the enhancer will be invoked automatically during the process-classes goal in the package phase of the Maven build.

Exclude references from the Persistence Unit

To exclude existing domain classes and/or metadata ORM files, you can add to the exclusion lists persistenceMappingExcludedClasses and persistenceMappingExcludedFiles respectively. These can be found in the core extension’s ep-core-plugin.xml file.

Override Persistence Unit Properties

Occasionally you may wish to override some of the properties defined in the core persistence unit, or add new properties. To do so, add the properties to the persistencePropertyOverrides map in the core extension’s ep-core-plugin.xml file. Do not add or change properties in any of the jpa-persistence.xml files, as the order in which these files are resolved cannot be guaranteed.