Configuring the Business Object Mediator

You can use XML configuration data to configure the Business Object Mediator. This XML can also be generated by the Data Service Layer wizard.

Before you begin

Object-relational metadata and physical SDO Java classes for your schema customization are generated by using the Data Service Layer Wizard, following the steps in Building metadata and data objects to reflect Data Service Layer schema changes.

About this task

The schema (both logical and physical) can be extended to add an extension table which has a one-to-one or one-to-many relation to an existing WebSphere Commerce table. This data is represented as name-value pairs in the logical model and is associated with an existing object in the model in the UserData area. In the physical model, this data is represented as a new table that has a foreign key to the base table.

To allow updates, a customer defines a new query to retrieve data from both the default and custom tables. The wc-business-object-mediator.xml needs to be updated to provide the appropriate change mediator with the new custom access profile. An in-depth coverage of the process is demonstrated in Tutorial: Extending a BOD service to manage UserData with the Data Service layer.

Note: Each change part mediator is fixed to a specific noun part, and one or more physical data objects. A change part mediator has to implement the getNounPartXPaths method to return an array of XPath which the change part mediator handles. Since the XPath cannot be changed unless the underlying mediator is in turn also changed, the XPath is defined in the Java code.

An example for defining the XPath is as follows:

For a change action <oa:ActionExpression actionCode="Change" expressionLanguage="_wcf:XPath">/Project[1]/Material[1]oa:ActionExpression actionCode="Change" expressionLanguage="_wcf:XPath">/Project[1]/Material[1]>, add the line <_config:part-mediator-implementation className="com.mycompany.commerce.project.facade.server.services.dataaccess.bom.mediator.ChangeProjectMaterialMediator" /> to the wc-business-object-mediator.xml file. Then, define the XPath private static final String[] XPATH = new String[] { "/Material[]" } ; to the ChangeProjectMaterialMediator.java file. Note that private static final String[] XPATH = new String[] { "/" } ; is present in the ChangeProjectBasePartMediator.java file.

The wc-business-object-mediator.xml configuration performs the following functions:

It links the logical noun (for example, CatalogEntryType) to your custom physical type (for example MyCompanyCatalogCatalogEntry). These mappings are created to facilitate the flow of custom data stored in the database to the client of the service. The logical properties are exposed as name-value pairs in the UserData element of the business objects.
It instructs the Business Object Mediator to use the appropriate methods on your physical SDO Java class (for example MyCompanyCatalogCatalogEntry) to add information to the user data element in the logical model (in our example, CatalogEntryType).
This file also configures the Read and Change mediators for business objects and business object parts.

If you are extending a WebSphere Commerce noun, use this file to change the mapping between the class used to store the logical object and the class that stores the physical object. In particular, you can change the physical class to be a customized physical class. It is this class that contains all of the methods to access your new data. After this, the DSL framework will use your physical object class instead of the default WebSphere Commerce class.

You can use the Data Service Layer wizard to generate this file and the appropriate mappings, or provide the mappings manually.

Procedure

Right-click the WC\config\com.ibm.commerce.myservicemodule-ext folder.
If wc-business-object-mediator.xml does not already exist in that directory, select New > Other > XML > XML > Next.
1. Select Create an XML file from scratch.
2. Click Next.
3. Name the file: wc-business-object-mediator.xml.
4. Click Finish.
Note: The Data Service Layer Wizard generates this file when customizing an existing WebSphere Commerce service module.
If wc-business-object-mediator.xml does already exist, open the file for editing to configure your Business Object Mediator.

Use this file to map your logicalType to your physicalType, and all of your physicalPropertyName to the correct logicalName. This file is created and populated when you run the Data Service Layer Wizard, so you will rarely need to make adjustments to this file.

The following example maps the MyCompanyCatalogCatalogEntry physical SDO to the CatalogEntryType noun, and creates relationships for warranty and wardesc:

<_config:BusinessObjectMediatorConfiguration xmlns:_config="http://www.ibm.com/xmlns/prod/commerce/foundation/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ibm.com/xmlns/prod/commerce/foundation/config ../xsd/wc-business-object-mediator.xsd">
  <_config:object 	logicalType="com.ibm.commerce.catalog.facade.datatypes.CatalogEntryType" 
									physicalType="com.ibm.commerce.catalog.facade.server.entity.datatypes.CatalogEntry">
    <_config:property-mapping logicalType="com.ibm.commerce.catalog.facade.datatypes.CatalogDescriptionType" physicalType="com.mycompany.commerce.catalog.facade.server.entity.datatypes.MyCompanyCatalogEntryDescription">
      <_config:child-property-mapping relationshipName="XcareinstructionForCatentdesc">
        <_config:userDataProperty logicalPropertyName="careinstruction" physicalPropertyName="careinstruction"/>
      </_config:child-property-mapping>
    </_config:property-mapping>
  </_config:object>
  <_config:object logicalType="com.ibm.commerce.catalog.facade.datatypes.CatalogEntryType" physicalType="com.mycompany.commerce.catalog.facade.server.entity.datatypes.MyCompanyCatalogEntry">
    <_config:property-mapping logicalType="com.ibm.commerce.catalog.facade.datatypes.CatalogEntryType" physicalType="com.mycompany.commerce.catalog.facade.server.entity.datatypes.MyCompanyCatalogEntry">
      <_config:child-property-mapping relationshipName="XwarrantyForCatentry">
        <_config:userDataProperty logicalPropertyName="warterm" physicalPropertyName="warterm"/>
        <_config:userDataProperty logicalPropertyName="wartype" physicalPropertyName="wartype"/>               
      </_config:child-property-mapping>
    </_config:property-mapping>
  </_config:object>
</_config:BusinessObjectMediatorConfiguration>

Looking at the XML example, we can see that it configures the data service layer to:

Link the logicalType com.ibm.commerce.catalog.facade.datatypes.CatalogEntryType to the physicalType com.ibm.commerce.catalog.facade.server.entity.datatypes.CatalogEntry
Link the logical attribute warterm with the physical property warterm.
Link the logical attribute wartype with the physical property wartype.
Link the logical attribute careinstruction with the physical property careinstruction.
Assign the physical property warterm to to a name-value pair in the UserData element of the BOD.
Assign the physical property wartype to a name-value pair in the UserData element of the BOD.
Create a method named getXwarrantyForCatentry() on the MyCompanyCatalogEntry physical SDO, which returns the Xwarranty physical SDO. This Xwarranty SDO has methods to retrieve warterm and wartype.

Note: In order to use the automatic UserData support you see illustrated in this task, the relationship between the base table and the extension table, each record in the base table can only map to one record in the extension table (an N to 1 relationship, where N is greater than 1).