Constant State Of Learning: WebSphere Commerce Data Services Layer

In my last post, I introduced concepts and layers around the BOD framework. Now I plan to dig a little more into the framework and discuss an important layer within the framework, DSL.

The WebSphere Commerce BOD framework often refers to the data services layer (DSL). For those familiar with the NVP command programming model, the DSL replaces the EJBs and Access Beans. It provides the abstract layer for data access decoupled from the physical database schema. I am going to try to pull some of the information together for a decent overview of DSL.

Here is a high level view from the info center of where in the architecture the DSL fits in.

As you can see, the DSL is core to the Persistence layer. Its purpose is to give a consistent interface for retrieving, changing, and deleting data that is not dependent on the object relational mapping. The communication between the layers, including the DSL, consists of SDOs (service data objects).

Service Data Object (SDO)
Around 2004 IBM and BEA developed the service data object (SDO) specification; the Java Community Process later accepted it (JSR 235). Service Data Objects are representations of data structures used for communication between various structural tiers. They are static or dynamic objects, which pertains to the properties or fields in the objects (static - fixed defined fields, dynamic - map-like for setting fields based on a configuration). If interested, here is more on the Java implementation of SDO: Using Service Data Objects (SDO).

The above diagram shows the use of SDOs between the layers and when accessing the database. This is because DSL comprises 2 types of SDOs (service data objects).

The 1st SDO set are the objects that represent your logical model (nouns).
The 2nd SDO set are a physical representation of the tables being read, updated or deleted. Each service data object consists of properties that correspond to a column in a table or refer to another data object type. These data object types define the foreign key relationships.

Physical SDOs and logical SDOs (those representing the logical model) are independent of each other. Physical SDOs are representations of data read from the database with the sql templates. This is where direct CRUD operations on the physical data take place.

So as you would assume there must be a way to map the physical SDOs to the logical SDOs. This mapping of physical SDOs and logical SDOs is where the Business object mediator service comes in.

Business Object Mediator
The Business Object Mediator controls the communication and mapping between the physical and logical SDOs. In the WCS data service layer there are 2 types of mediators: those that transform the 2 types of SDOs for read access (read mediators), and those that translate for create, update and delete operations (change mediators). The mapping between the logical SDO and physical SDO is maintained in the business object mediation XML configuration file (wc-business-object-mediator.xml), which can be generated with the Data Service Layer wizard. There is also a configuration file for mapping the physical SDO to the actual database schema, wc-object-relational-metadata.xml.

Each read mediator has a buildNoun or buildNounPart method with 2 parameters: aLogicalEntityType (logical SDO), and aPhysicalEntityType (physical SDO).

The change mediators consist of methods to aid in translating CRUD: validateCreate, validateChange, validateDelete, and create, update, delete, and getNounPartXPaths.

The above diagram shows the 3 main parts of the DSL; Data service facade, Business object mediation service and Physical persistence service. We already looked at the mediation service that translates between the physical and logical SDOs. The Data service facade simply provides a consistent interface for the DSL that allows for accessing data independent of the physical schema.

Physical persistence service
The final sub-layer of DSL is the physical persistence service. The mediators use this service to execute the CRUD actions on the physical data. The input query for this service is XPath that maps to corresponding SQL. Configuration of the SQL mapping is in files based on the SDO and the action. For example:

wc-query-<noun/nounpart>-get.tpl

The SQL template maps each get XPath statement to a SQL template.

wc-query-<noun/nounpart>-update.tpl

The SQL template mapping each change XPath request to a SQL template.

Below is an example configuration file for a SQL template from a tutorial in the info center.

<_config:table name="XWARRANTY" occColumnName="OPTCOUNTER" propertyName="Xwarranty">
<_config:column name="CATENTRY_ID" nullable="false" primaryKey="true" propertyName="catentry_id" type="BIGINT"/>

BEGIN_SYMBOL_DEFINITIONS


COLS:CATENTRY=CATENTRY:*
COLS:CATENTDESC=CATENTDESC:*


COLS:XWARRANTY=XWARRANTY:*
COLS:XCAREINSTRUCTION=XCAREINSTRUCTION:*

END_SYMBOL_DEFINITIONS

BEGIN_XPATH_TO_SQL_STATEMENT

name=/CatalogEntry[CatalogEntryIdentifier[(UniqueID=)]]+MyCompany_All
base_table=CATENTRY
sql=
SELECT
CATENTRY.$COLS:CATENTRY$,
CATENTDESC.$COLS:CATENTDESC$,
XWARRANTY.$COLS:XWARRANTY$,
XCAREINSTRUCTION.$COLS:XCAREINSTRUCTION$
FROM
CATENTRY
LEFT OUTER JOIN XWARRANTY ON (CATENTRY.CATENTRY_ID = XWARRANTY.CATENTRY_ID)
LEFT OUTER JOIN CATENTDESC ON (CATENTDESC.CATENTRY_ID = CATENTRY.CATENTRY_ID
AND CATENTDESC.LANGUAGE_ID in ($CONTROL:LANGUAGES$))
LEFT OUTER JOIN XCAREINSTRUCTION ON (CATENTRY.CATENTRY_ID = XCAREINSTRUCTION.CATENTRY_ID
AND XCAREINSTRUCTION.LANGUAGE_ID = CATENTDESC.LANGUAGE_ID)
WHERE
CATENTRY.CATENTRY_ID IN (?UniqueID?) AND
CATENTRY.MARKFORDELETE = 0
END_XPATH_TO_SQL_STATEMENT

The two subsections of this example query template are:

SYMBOL_DEFINITIONS

This defines symbols for the columns in your SQL. When adding or removing columns, you can adjust the symbols without rewriting all of your SQL.

XPATH_TO_SQL_STATEMENT

This maps an XPath expression to an SQL statement. The above example defined the mapping, named it using the XPath expression (/CatalogEntry[CatalogEntryIdentifier[(UniqueID=)]]+MyCompany_All), and mapped it to the base table and SQL statement.

XPath
You may have noticed that in the first diagram and in the last section the reference to XPath. The BOD/DSL programming model uses XPath to communicate between the business logic and logical schema and the DSLs physical persistence service. XML Schema's define nouns (logical SDOs), because of this IBM chose to use XPath. So WCS uses XPath to query XML documents. The XPath expressions map a data request to the SQL to carry out the request.

Following shows the XPath components from Viewing your XPath key in the info center.

{control parameters}/root node[predicate expressions]

And in use it would look something like this (based on the above example in info center):

/CatalogGroup[Identifier='MyCatalogGroupIdentifier']

The above example is requesting the CatalogGroup noun with the identifier of "MyCatalogGroupIdentifier". The root node in the example is the requested object for the response (in this case, CatalogGroup).

The example XPath expression is mapped to corresponding SQL in the XPATH_TO_SQL_STATEMENT section of a SQL mapping file, wc-query-CatalogGroup-get.tpl.
The example would look roughly like this:

BEGIN_XPATH_TO_SQL_STATEMENT
name=/CatalogGroup[Identifier=]
base_table=CATGROUP
sql=
SELECT
CATGROUP.$COLS:CATGROUP$
FROM
CATGROUP
WHERE
CATGROUP.IDENTIFIER= ?Identifier?
END_XPATH_TO_SQL_STATEMENT

Well I hope that this helps summarize and introduce the main concepts of the DSL portion of the BOD programming model. Next, I will discuss; customizing BOD Commands, the WCS wizards, and how all of the configuration files in this programming model fit together.

Resource Links:

3 comments:

Francesco SchettiniOctober 3, 2014 at 12:51 AM
Well done Marcus, thanks for sharing.
AnonymousNovember 28, 2014 at 10:40 PM
Great explanation and wonderfully written. Thanks so much.
UnknownFebruary 18, 2015 at 1:52 AM
Hi Marcus,

Access Profiles are used with xpath expression to identify a sql query in tpl file.

From the Infocenter BOD tutroial, ,I have 2 doubts
1. For READ access profiles are used and they are passed in AbstractBusinessObjectDocumentFacadeClient.createGetVerb()
but in Change proceess we didn't passed access profiles
So if we are not passing access profiles how they are reaching a particular sql query.

2. For the Change process, change Project Name they passed xpath as
/Project[{0}] but in update tpl file they are referring to /Project[ProjectIdentifier[UniqueID=]]
How they are reaching to this expression?

Thursday, February 13, 2014

WebSphere Commerce Data Services Layer

3 comments: