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.
<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.
- 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 directory.
- Copy the source files generated in the \output to the
WebSphereCommerceServerExtensionsData project in the
workspace. That is, copy it to the directory: .
To fix the compilation errors for the generated custom SDO and JPA, you need to add the following jar in the java build path:
.
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
Database migration for custom tables
-
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.