Customizing the physical layer to include the new information

In this lesson you are customizing the physical layer by modifying the WebSphere Commerce schema, generating object-relational metadata, and generating physical service data objects (SDOs). To do so, you use a tool called the Data Service Layer wizard.

About this task

The Data Service Layer wizard is used to generate object-relational metadata and physical data objects for your schema customization. Physical SDOs are service data objects that represent tables in the WebSphere Commerce schema. Each data object type corresponds to a table definition in the schema, and each data object property corresponds to a table column or a reference to another DataObject type. These references correspond to the foreign key relationships between the database tables.

For each service module, there is object-relational metadata that contains the information to relate the physical DataObject to a database table. Custom object-relational metadata is stored in the component configuration extension directories and custom physical SDOs are stored inside the WebSphereCommerceServerExtensionsLogic project.

This wizard performs the following tasks:

Creates an extension configuration folder for the Catalog service module if one does not exist. The directory path is: WC_eardir\xml\config\com.ibm.commerce.catalog-ext.
Generates a custom object-relational metadata file that describes the new custom tables and relationships. In this tutorial, the metadata file describes the two new tables, XWARRANTY and XCAREINSTRUCTION, along with the three new relationships between tables:
- XWARRANTY and CATENTRY
- XCAREINSTRUCTION and CATENTRY
- XCAREINSTRUCTION and CATENTDESC
This file location is WC_eardir\xml\config\com.ibm.commerce.catalog-ext\wc-object-relational-metadata.xml.
Note: The wc-object-relational-metadata.xml file maps the database tables and columns to physical SDOs.
For example, the following snippet of the XWARRANTY configuration as generated by the DSL wizard in this tutorial:
```
<_config:table name="XWARRANTY" occColumnName="OPTCOUNTER" propertyName="Xwarranty">
    <_config:column name="CATENTRY_ID" nullable="false" primaryKey="true" propertyName="catentry_id" type="BIGINT"/>
```
Where the column CATENTRY_ID is mapped to the field catentry_id in the XWarranty Java class.
Generates an SDO Java class and places it in the WebSphereCommerceServerExtensionsLogic project for:
- Each new custom table (XWARRANTY and XCAREINSTRUCTION).
- Each modified WebSphere Commerce table (CATENTRY and CATENTDESC were modified by adding new relationships to the custom tables).
Physical SDOs are service data objects that represent tables in WebSphere Commerce. For each table, there is one DataObject that represents the tables, columns, and relationships.
Creates a utility Java class to return the physical SDO root class (and its package) for the service module. This root class ensures that all WebSphere Commerce physical SDOs for the Service Module, and any additional physical SDOs for the customization, are available at run time.
Creates an extension service module configuration file that instructs WebSphere Commerce to use the newly created catalog physical SDO class in WC_eardir\xml\config\com.ibm.commerce.catalog-ext\wc-component.xml.
Creates an extension business object mediator configuration file. This file configures the business object mediator to include data from the XWARRANTY and XCAREINSTRUCTION tables in the user data of a CatalogEntry noun. This file location is WC_eardir\xml\config\com.ibm.commerce.catalog-ext\wc-business-object-mediator.xml.

Procedure

To begin customizing the physical layer:

Use the Data Service Layer wizard to generate object-relational metadata and physical data objects that represent the customized schema.
1. If your development environment uses an Apache Derby database, ensure that there is no existing connection to it. For example, ensure that the WebSphere Commerce server is stopped.
2. Select File > New > Other > WebSphere Commerce > Data Service Layer.
3. Click Next.
4. Select Extend a default WebSphere Commerce service module
5. Click Next.
6. Enter the following information:
  - Service module: Select com.ibm.commerce.catalog
  - Extension class prefix: MyCompany
  - Extension Java package name: com.mycompany.commerce.catalog
7. Click Next.
8. Select the XCAREINSTRUCTION and XWARRANTY tables.
9. Click Next.
10. Under UserData, ensure the Warterm, Wartype, and Careinstruction database columns are set to True. Set the other columns to False if they are set as True by default.
11. If you are using the Oracle database in your WebSphere Commerce Developer environment, under the Datatypes column, select INTEGER for the LANGUAGE_ID row.
12. Click Finish.
The following step is necessary only if your WebSphere Commerce Developer environment uses the Oracle database.
The Oracle NUMBER data type can represent different number types, including integer, float, and double. However, the data service layer requires all columns to be resolved to specific types. When generating object-relational metadata and physical service data objects, the wizard assumes that other columns with a data type of NUMBER default to long. You can specify other data types, such as: BIGINT, SMALLINT, and DECIMAL. If a different data type is required, the object-relational metadata XML file must be changed.
To update the column attribute:
1. Open WC_eardir\xml\config\servicemodulepackagename-ext\wc-object-relational-metadata.xml.
2. Update the type attribute for the LANGUAGE_ID column.
  Find the section that corresponds to the following XML sample:
```
<_config:table name="XCAREINSTRUCTION" occColumnName="OPTCOUNTER" propertyName="Xcareinstruction">
    <_config:column name="CATENTRY_ID" nullable="false" primaryKey="true" propertyName="catentry_id" type="NUMBER"/>
    <_config:column name="LANGUAGE_ID" nullable="false" primaryKey="true" propertyName="language_id" type="NUMBER"/>
    <_config:column name="DESCRIPTION" nullable="true" primaryKey="false" propertyName="description" type="VARCHAR2"/>
    <_config:column name="OPTCOUNTER" nullable="true" primaryKey="false" propertyName="optcounter" type="SMALLINT"/>
</_config:table>
```
  Change this LANGUAGE_ID column data type from NUMBER (which would default to Long) to INTEGER, as shown in the following XML sample:
```
<_config:table name="XCAREINSTRUCTION" occColumnName="OPTCOUNTER" propertyName="Xcareinstruction">
    <_config:column name="CATENTRY_ID" nullable="false" primaryKey="true" propertyName="catentry_id" type="NUMBER"/>
    <_config:column name="LANGUAGE_ID" nullable="false" primaryKey="true" propertyName="language_id" type="INTEGER"/>
    <_config:column name="DESCRIPTION" nullable="true" primaryKey="false" propertyName="description" type="VARCHAR2"/>
    <_config:column name="OPTCOUNTER" nullable="true" primaryKey="false" propertyName="optcounter" type="SMALLINT"/>
</_config:table>
```
3. Repeat step 1. The wizard removes the existing SDOs for the table and generate new SDOs with the new data type.
  Note: The custom table is preselected for you, when you repeat step 1 g.

Results

If the code generated by the Data Service Layer produces an error, for example, CatalogEntityPackage cannot be resolved, selecting Project > Clean can resolve the issue.