You can extend the commerce object hierarchy by subclassing an existing object and adding new properties. When you add simple data type properties such a strings, you do not need to write any code to save the properties to or load the properties from the Order Repository. Using introspection, the processors in the updateOrder and loadOrder pipelines handle this automatically.
As an example, the following code creates a new class called MyCommerceItemImpl. It extends CommerceItemImpl and adds a new String property called shortDescription.
import atg.commerce.order.CommerceItemImpl;
public class MyCommerceItemImpl extends CommerceItemImpl {
public MyCommerceItemImpl() {
}
public String getShortDescription() {
return (String) getPropertyValue("shortDescription");
}
public void setShortDescription(String pShortDescription) {
setPropertyValue("shortDescription", pShortDescription);
}
}In the code example above, note the calls to getPropertyValue() and setPropertyValue(). These methods retrieve and set the values of properties directly on the repository item objects; they are part of the atg.commerce.order.ChangedProperties interface. In a commerce object that supports the ChangedProperties interface, every get method needs to call the getPropertyValue method, and similarly every set method needs to call the setPropertyValue method. In Core Commerce, all commerce objects implement the ChangedProperties interface except for atg.commerce.order.AuxiliaryData and all subclasses of atg.commerce.pricing.AmountInfo.
The ChangedProperties interface enhances performance when saving an Order to the Order Repository. In the example above, the call to setPropertyValue("shortDescription", pShortDescription) in the setShortDescription method causes the shortDescription repository item property to be set directly when the method is called. This approach reduces the amount of processing when OrderManager.updateOrder() is called to save the Order to the repository. Performance is enhanced because you set the values directly to the repository item and only save the properties that have actually been changed in the class. The call to getPropertyValue("shortDescription") retrieves the property directly from the repository item and eliminates the need to create a member variable in the class to store the value.
With the MyCommerceItemImpl subclass created, you now need to integrate the new commerce object into Core Commerce. You can do so using one of two approaches:
(Recommended) If you want your extensions in all objects, add the new properties to an existing item descriptor and then map the new object to that item descriptor. This approach is recommended because it eliminates the need to change property values that contain item descriptor names throughout Core Commerce. For more information, see Integrating a New Commerce Object: Using an Existing Item Descriptor, which continues the example of
MyCommerceItemImpl.Create a new item descriptor subtype that includes the new properties and map the new object to it. For more information, see Integrating a New Commerce Object: Using a New Item Descriptor, which continues the example of
MyCommerceItemImpl.
Note: You can also extend the commerce object hierarchy by subclassing AuxiliaryData, which holds auxiliary data for a CommerceItem. If you do so, you can integrate the new class into Core Commerce using either process described in this section. (Recall that AuxiliaryData does not implement the ChangedProperties interface.) However, you should take the following additional steps:
Override the
createAuxiliaryDatamethod in the subclass so that it creates an instance of that new class, as follows:protected void createAuxiliaryData() {
if (mAuxiliaryData == null) {
mAuxiliaryData = new MyAuxiliaryData(getRepositoryItem());
}Ensure the new properties of the subclass are defined within the XML definition for the new commerce object.
Ensure the database columns that store the new properties of the subclass go into the table that represents the new commerce object.
Integrating a New Commerce Object: Using an Existing Item Descriptor
To integrate MyCommerceItemImpl into Core Commerce using an existing item descriptor, follow the steps described in this section.
Extend the Order Repository Definition File
Extend the Order Repository definition file, orderrepository.xml, to add the new properties in MyCommerceItemImpl to the existing commerceItem item descriptor. In this example, the new property to add is the shortDescription property.
The orderrepository.xml file is found in the CONFIGPATH at /atg/commerce/order/orderrepository.xml. To extend the file, create a new orderrepository.xml file at /atg/commerce/order/ in your localconfig directory. The new file should define the shortDescription property for the commerceItem item descriptor. During deployment, the Oracle Commerce Core Platform uses XML file combination to combine the orderrepository.xml files in the CONFIGPATH into a single composite XML file. (For more information on XML file combination, see the Nucleus: Organizing JavaBean Components chapter in the Platform Programming GuidePlatform Programming Guide.)
The orderrepository.xml file that you create might look as follows:
<gsa-template xml-combine="append"> <item-descriptor name="commerceItem"> <table name="dcspp_my_item" id-column-name="commerce_item_id"> <property name="shortDescription" column-name="short_description" data-type="string"/> </table> </item-descriptor> </gsa-template>
The first line in the above XML example begins the GSA template and instructs the XML combiner to append the contents of the tags in this file to the contents of the tags in the file with which it is combined.
The next section defines the shortDescription property of a commerceItem repository item, as well as the database table and column that store that property.
For more information on setting up a repository and defining item descriptors, see the Repository Guide.
Modify the Order Repository Database Schema
In step 1, you defined the new shortDescription property of the commerceItem item descriptor, specifying the database table and column that store that property. Now you need to modify accordingly the Order Repository database schema.
The following DDL statement creates the database table and columns specified in the orderrepository.xml file that you created in step 1.
CREATE TABLE dcspp_my_item ( commerce_item_id VARCHAR(40) NOT NULL REFERENCES dcspp_item(commerce_item_id), short_description VARCHAR(254) NULL, PRIMARY KEY(commerce_item_id) );
Modify the OrderTools Configuration File
The OrderTools component controls many aspects of the purchase process, such as mapping between commerce object types and class names, defining the default commerce object types, and mapping between commerce objects and item descriptors. You need to modify the OrderTools configuration file to support the new MyCommerceItemImpl class.
To modify the OrderTools configuration file, layer on a configuration file by creating an OrderTools.properties file at /atg/commerce/order/ in your localconfig directory. The OrderTools.properties file might look as follows:
beanNameToItemDescriptorMap-=\ atg.commerce.order.CommerceItemImpl=commerceItem beanNameToItemDescriptorMap+=\ my.class.dir.MyCommerceItemImpl=commerceItem commerceItemTypeClassMap+=\ default=my.class.dir.MyCommerceItemImpl
The beanNameToItemDescriptorMap property maps Order Repository item descriptors to Bean names. In Core Commerce, the processors that save and load an Order look for an item descriptor that is mapped to the corresponding commerce object class; the beanNameToItemDescriptorMap property contains this mapping. The configuration file above first removes the out-of-the-box configuration, then remaps the existing commerceItem item descriptor to the new Bean class, MyCommerceItemImpl. The my.class.dir prefix specifies some Java package in which the class exists.
Because you can have more than one type of CommerceItem object, the commerceItemTypeClassMap property maps CommerceItem types to class names. This mapping is used by the createCommerceItem method in the CommerceItemManager; by passing it a type parameter (such as the string “default”), the method constructs and returns an instance of the corresponding class. When one of the createCommerceItem methods that does not take a type parameter is called, the method constructs and returns an instance of the type specified in OrderTools.defaultCommerceItemType. By default, the defaultCommerceItemType property is set to the type default, which, in turn, is mapped to the new MyCommerceItemImpl class in the commerceItemTypeClassMap property in the configuration file above. The my.class.dir prefix indicates some Java package in which the class exists.
Integrating a New Commerce Object: Using a New Item Descriptor
To integrate MyCommerceItemImpl into Core Commerce using a new item descriptor subtype, follow the steps in the following sections. This approach is most useful when you have an alternative subclass of the runtime object (as opposed to replacing the runtime object). If you have two object classes, you might add a new entry instead of reconfiguring the default entry in the commerceItemTypeClassMap.
Step 1 of 4 - Extend the Order Repository Definition File
Extend the Order Repository definition file, orderrepository.xml, to create a new item descriptor subtype that supports the new properties in MyCommerceItemImpl.
The orderrepository.xml file is found in the CONFIGPATH at /atg/commerce/order/orderrepository.xml. To extend the file, create a new orderrepository.xml file at /atg/commerce/order/ in your localconfig directory. The new file should define the new item descriptor subtype. During deployment, the Core Commerce platform uses XML file combination to combine the orderrepository.xml files in the CONFIGPATH into a single composite XML file. (For more information on XML file combination, see the Nucleus: Organizing JavaBean Components chapter in the Platform Programming Guide.)
The following orderrepository.xml file defines a new item descriptor named myCommerceItem. As a subtype of the commerceItem item descriptor, myCommerceItem inherits all of the properties of commerceItem. Additionally, it defines one new property, shortDescription.
<gsa-template xml-combine="append"> <item-descriptor name="commerceItem"> <table name="dcspp_item"> <property name="type"> <option value="myCommerceItem" code="1"/> </property> </table> </item-descriptor> <item-descriptor name="myCommerceItem" super-type="commerceItem" sub-type-value="myCommerceItem"> <table name="dcspp_my_item" id-column-name="commerce_item_id"> <property name="shortDescription" column-name="short_description" data-type="string"/> </table> </item-descriptor> </gsa-template>
The first line in the above XML example begins the GSA template and instructs the XML combiner to append the contents of the tags in this file to the contents of the tags in the file with which it is combined.
The next section defines myCommerceItem as a subtype of the commerceItem item descriptor. You do this by adding a new string value for myCommerceItem to the type enumerated property of commerceItem. In this case, the new type is called myCommerceItem, and its corresponding integer value is 1. The base orderrepository.xml file contains the other options for the type property of commerceItem.
The last section of the XML file defines the myCommerceItem item descriptor, specifying commerceItem as the super-type (or parent item descriptor) and myCommerceItem as the sub-type-value. The section then specifies the properties of a myCommerceItem repository item, as well as the database table and columns that store those properties. In this case, a single property, shortDescription, is specified. However, recall that myCommerceItem inherits all of the properties of commerceItem, its parent item descriptor.
For more information on setting up a repository and defining item descriptors, see the Repository Guide.
Step 2 of 4 – Modify the Order Repository Database Schema
In step 1, you created the new myCommerceItem item descriptor, defining both its properties and the database table and columns that store those properties. Now you need to modify accordingly the Order Repository database schema.
The following DDL statement creates the database table and columns specified in the orderrepository.xml file that you created in step 1.
CREATE TABLE dcspp_my_item ( commerce_item_id VARCHAR(40) NOT NULL REFERENCES dcspp_item(commerce_item_id), short_description VARCHAR(254) NULL, PRIMARY KEY(commerce_item_id) );
Step 3 of 4 – Modify the OrderTools Configuration File
The OrderTools component controls many aspects of the purchase process, such as mapping between commerce object types and class names, defining the default commerce object types, and mapping between commerce objects and item descriptors. You need to modify the OrderTools configuration file to support the new MyCommerceItemImpl class and myCommerceItem item descriptor.
To modify the OrderTools configuration file, layer on a configuration file by creating an OrderTools.properties file at /atg/commerce/order/ in your localconfig directory. The OrderTools.properties file might look as follows:
beanNameToItemDescriptorMap+=\ my.class.dir.MyCommerceItemImpl=myCommerceItem commerceItemTypeClassMap+=\ default=my.class.dir.MyCommerceItemImpl
The beanNameToItemDescriptorMap property maps Order Repository item descriptors to Bean names. In Core Commerce, the processors that save and load an Order look for an item descriptor that is mapped to the corresponding commerce object class; the beanNameToItemDescriptorMap property contains this mapping. The configuration file above adds a new entry, mapping the myCommerceItem item descriptor that you created in step 1 to the MyCommerceItemImpl class. The my.class.dir prefix specifies some Java package in which the class exists.
Because you can have more than one type of CommerceItem object, the commerceItemTypeClassMap property maps CommerceItem types to class names. This mapping is used by the createCommerceItem method in the CommerceItemManager; by passing it a type parameter (such as the string “default”), the method constructs and returns an instance of the corresponding class. When one of the createCommerceItem methods that does not take a type parameter is called, the method constructs and returns an instance of the type specified in OrderTools.defaultCommerceItemType. By default, the defaultCommerceItemType property is set to the type default, which, in turn, is mapped to the new MyCommerceItemImpl class in the commerceItemTypeClassMap property in the configuration file above. The my.class.dir prefix indicates some Java package in which the class exists.
Step 4 of 4 – Extend the ID Spaces Definition File
Note: Because the example provided throughout this section involves an item descriptor subtype rather than a root item descriptor, this step is not required for the example. It is provided here for information when defining root item descriptors.
When an ID is requested for a new repository item, it is requested from the appropriate IdSpace for that repository item. The item descriptor’s id-space-name attribute specifies which IdSpace supplies repository IDs for items of that item type. By default, all items use the item descriptor’s name as the ID space unless their item type inherits from another item type. In the latter case, the items use the ID space name of the root item descriptor in the super-type hierarchy.
If the new item descriptor that you’ve defined is a root item descriptor, you need to extend the ID spaces definition file, idspaces.xml, in order to define an ID space for that item descriptor. The Core Commerce IdGenerator guarantees that IDs within a named ID space are unique, and each root item descriptor defines the characteristics of its ID space in the idspaces.xml definition file.
Because the example used throughout this section involves the myCommerceItem item descriptor subtype, which is a subtype of the commerceItem item descriptor, it does not require a defined ID space. However, if myCommerceItem were a root item descriptor, you would define an ID space for it by creating a new idspaces.xml file at /atg/dynamo/service/ in your localconfig directory. During deployment, the Oracle Commerce Core Platform uses XML file combination to combine the idspaces.xml files in the CONFIGPATH into a single composite XML file. (For more information on XML file combination, see the Nucleus: Organizing JavaBean Components chapter in the Platform Programming Guide.) The idspaces.xml file might look as follows:
<id-spaces xml-combine="append"> <id-space name="myCommerceItem" seed="1" batch-size="10000" prefix="mci"/> </id-spaces>
For more information on defining ID spaces and its impact on repository item IDs, see the ID Generators section of the Core Dynamo Services chapter in the Platform Programming Guide.
