Replacing Eclipse Modeling Framework (EMF) physical Service Data Objects (SDO) with Eclipselink SDO linked with Java Persistence API (JPA)

HCL Commerce Business Object Document (BOD) service

When a client sends a Business Object Document (BOD) service request to the server, the server BOD service framework will pass it to the corresponding component mediator. If it is a process or change request, the data area in the BOD is a logical Service Data Objects (SDO). The mediator will convert it to a list of physical SDO, and the Data Service Layer (DSL) JDBCDataMediator will send these physical SDOs to IBM JDBCMediator to persist. If it is a read request, the read mediator will get the XPath and access profile in the BOD and send it to the DSL. The DSL will obtain the relevant SQLs and the JDBCDataMediator in HCL Commerce before sending the SQLs to the IBM JDBCMediator to retrieve the database's contents. The IBM JDBCDataMediator will build a physical SDO graph based on the query result provided from the database and then return this graph to the JDBCDataMediator. When the component mediator gets the physical SDO graph, it will convert it back to the logical SDO and the BOD service framework will build a BOD and send it back to the client.

The following diagram illustrates the work flow for the existing commerce BOD service:

EMF SDO

Currently, the physical SDOs used in the BOD service are EMF SDOs. The persistence layer relies on the IBM JDBCMediator to read and persist the data to the database. Since it is IBM proprietary technology and is not open-sourced, the EMF SDO is replaced with the EclipseLink SDO and the persistence layer is replaced with with Java Persistence API (JPA).

Eclipselink SDO with JPA

EclipseLink provides an open-source Java persistence solution that includes the support of the JPA and SDO. For more information, see EclipseLink/Examples/SDO/JPA. With EclipseLink, each SDO will be linked with a JPA object. Whatever changes in the SDO will be reflected in the linked JPA, and the JPA entity manager will persist it. The SDO and JPA can be generated by an XML schema definition (XSD) file which defines the SDO interfaces.

HCL Commerce BOD service

The following diagrams illustrate the new workflow for the BOD service:

The original BOD service with EMF SDO:
The BOD service with Eclipselink SDO:
The JDBCMediator has been replaced with the JPADataMediator, and the IBM JDBCMediator has been replaced with JPA entity manager.

Steps to enable all components to use JPA mediator

Updating the file wc-server.xml in the directory xml\config by adding an attribute DataServiceMediatorType to the Instance tag.

For example:

<Instance
   ...
   DataServiceMediatorType="JPA" />

The acceptable values for the data mediator type are JPA or JDBC. Any other values will be ignored.

Customization

Suppose a customer did a customization based on the Warranty Tutorial to extend the catalog tool in the management center, before enabling the new EclipseLink SDO linked with JPA. In that case, they must migrate their customization to this new environment. They also need to migrate their custom EMF SDOs to the EclipseLink SDO linked with JPA. HCL Commerce provides a tool to help customers to generate the new custom SDO linked with JPA.

In the Commerce development environment (toolkit), customers have the customization. The custom configuration files have already been generated in the directory: WC > xml > config > com.ibm.commerce.catalog-ext. Customers must run the generateCustomSdoJpa.bat to generate the custom EclipseLink SDO and JPA files. The generateCustomSdoJpa.bat file can be found under the bin directory. The script takes two parameters:

The component ID. For example, the component ID for the catalog component is com.ibm.commerce.catalog.
The output directory where the EclipseLink SDO and JPA files will be generated. For example, it can be \output.

Do the following steps:

Run the following command:
```
bin> generateCustomSdoJpa.bat com.ibm.commerce.catalog \output
```
The SDO and JPA source files will be generated in the \output directory. It also generates an XSD file catalog-ext.xsd in the WC > xml > config > com.ibm.commerce.catalog-ext directory.
Copy the source files generated in the \output to the WebSphereCommerceServerExtensionsData project in the workspace. That is, copy it to the directory: WebSphereCommerceServerExtensionsData > ejbModule.
To fix the compilation errors for the generated custom SDO and JPA, you need to add the following jar in the java build path: WC > Foundation-SDO-JPA.jar.

Note: Do not run the script to generate the SDO and JPA source code directly to the WebSphereCommerceServerExtensionsData > ejbModule directory. The script will clean up the output directory and may delete some existing files in the output directory, which you may want to keep. So always generate the files in a new or an empty directory and then copy all generated files to WebSphereCommerceServerExtensionsData > ejbModule directory.

Now you can test your customization with the eclipselink SDO and JPA enabled in your toolkit.

You can also deploy your customization to the ts-app docker container to test to see if the customization also works in the ts-app docker container with the EclipseLink SDO and JPA enabled. To deploy it to the ts-app docker container, you must package the WebSphereCommerceServerExtensionsData.jar to the ts-app docker container. You also need to deploy the catalog-ext.xsd to the ts-app docker container by copying the file to the directory: /opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/com.ibm.commerce.catalog-ext

The tool which generates the EclipseLink SDO and JPA is also available in the ts-utils docker container. The name of the script file is generateCustomSdoJpa.sh. The parameters of the script are the same as in the toolkit. Before calling the script, you need to copy your existing EMF SDO custom configuration files to ts-utils docker container in the following directory: /opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/com.ibm.commerce.catalog-ext

Note: Ensure that none of the customization codes utilizes any of the Java implementation classes of the SDO. If so, you must change the customization code to switch to using the Java interface classes of the SDO.

Database migration for custom tables

The OPTCOUNTER field cannot have a null value, according to JPA. With the migration to V9, all standard tables now feature the OPTCOUNTER column with a default value of 0. It also needs to create an OPTCOUNTER column with non-null values for any custom tables. For instance, the custom tables XWARRANTY and XCAREINSTRUCTION can be used with the following SQL statements:

UPDATE XWARRANTY SET OPTCOUNTER = 0 WHERE OPTCOUNTER IS NULL;

UPDATE XCAREINSTRUCTION SET OPTCOUNTER = 0 WHERE OPTCOUNTER IS NULL;

For more information on OPTCOUNTER, see Optimistic locking.