Extending a noun

There are two methods for adding more information to the noun. The simplest method is to leverage the UserData extension points that the component nouns provide. The alternative is to take advantage of the overlay methodology. Overlay extensions allow users to have their extensions appear within the OAGIS or WebSphere Commerce complex types. In order to add elements, a user must extend the OAGIS or WebSphere Commerce complex types within their own namespace. By doing this, it is possible for users to enforce additional restrictions or add additional elements to the OAGIS or WebSphere Commerce complex types.

• Add more data using the UserData extension points: To use this simple approach of adding more information to the request, do the following updates.

  1. Identify the client library that populates the noun and extend it. The extension will populate the UserData elements of the Noun to contain the additional information.

     For example, if you are adding a new attribute such as engraving data to a set of order items, you would add the following code to the buildOrderItems method.

     for (int i=0; i<orderItems.length; i++) //for all of the order
     items
     {
             OrderItemType orderItem = orderItems[i]; //get a particular
     orderItem
             //prepare the userData section
             UserDataType userData = orderItem.getUserData();
             if (userData == null)
             {
                     userData =
     CommerceFoundationFactory.eINSTANCE.createUserDataType();
             }
             orderItem.setUserData(userData);
             Map userDataFields  = userData.getUserDataField();
     
             //iterate through all the engraving parameters
             Set keys = parameters.keySet();
             Iterator it = keys.iterator();
             while (it.hasNext())
             {
                     String keyName = (String)it.next();
                     if (keyName.startsWith(ENGRAVINGKEYNAME))//if it is
     an engraving attribute
                     {
                             String[] values =
     (String[])parameters.get(keyName);
                             //create a new name, value pair type
                             userDataFields.put(keyName,values[i]);
                     }
             }
     }
     

     This adds the additional logic to populate the UserData extension. The result, in the BOD, should look like the following sample

     <_wcf:UserData>
     <_wcf:UserDataField
     name="engravingFont">Arial</_wcf:UserDataField>
     <_wcf:UserDataField name="engravingText">Happy
     Birthday</_wcf:UserDataField>
     <_wcf:UserDataField
     name="engravingColor">red</_wcf:UserDataField>
     </_wcf:UserData>
     

  2. Identify the service commands that require customization to handle the new information inside the extended UserData. Extend the command implementation, following one of the WebSphere Commerce service design patterns. For example, you can extend the performExecute() method of the ExtendOrderItemProcessCmdImpl task command to save the UserData from the request properties to the database.

     Request type
     Process, Change, or Sync	Update the service commands that should be able to handle the additional data. See the design pattern for Process, Change and Sync service implementation for more information.
     Get	Extend the Compose (or Format) task command implementation for the appropriate access profile to populate the additional information in the UserData element. See the design pattern for Get service implementation for more information.

  3. Register the new command implementation.

• Add more data using the overlay extension model:

  Adding more data using the overlay extension model requires more steps than the UserData approach. So for those cases where you cannot use the simple UserData approach to add more data for a given request, perform the following steps when overlaying the existing schema.

  1. Identify the noun of the component you want to extend. Extending the noun can consist of adding a new element to the noun or extending an existing complex type to contain more information.

  2. Create an XSD file using the recommended directory structure and your custom namespace that contains the extended complex type with the additional elements and attributes.

  3. In the XSD file, define an element that is of the complex type you created. This element should be declared as a substitution group of the element it can replace. For example

     <element name="ComplexObject"
     type="myco:MyOverlayComplexObjectType"
     substitutionGroup="_ord:ComplexObjectType"/>
     

  4. Create the Service Data Object genmodel file for the XSD files that contain the extension types.

  5. Generate the SDO code from the SDO genmodel file.

  6. Create an SDO.properties file in the xml/config/ folder to register the generated SDO package class. In order to support auto-detection of an XML document to the appropriate Java object, the SDO package implementation class needs to be registered in the application. The SDO.properties file supports the registration of SDO packages. An example of this file is as follows

     com.ibm.commerce.foundation-ext/SDO.properties
     

  7. Identify the client logic that populates the Noun Java object and add the additional logic to create the extended SDO object and populate it. This logic can either be other business logic that populates pieces of the noun and uses the client library to make the request, or it can be the client library.

     1. In the case where the business logic is the client library, the client library should be extended and the business logic should call the extended client library. For example, if the extension is adding more information for a Web based request, the map method of the client library is extended to handle the additional data; the action calling the library uses the extended client library.

  8. Identify the component commands that must be changed to handle the overlay structure. Extend the command implementation accordingly.

     1. In the case of a Process, Change, or Sync request, update the service commands that should be able to handle the additional data. When the message mapping template is used to call existing controller commands, create a copy of the existing template mapping and register the copy in the component-services-user-tempate.xml. Then add the overlay extension mapping to the copied template to account for the extended information added.

     2. In the case of a Get request, extend the Compose (or Format) task command implementation for the appropriate access profile to create the extended SDO that represents the overlay and populate it with the appropriate information.

  9. Register the new command implementation.

Since you own all the new data objects you define, any object that uses or extends common objects should be put under your namespace. That is, you should not add new datatypes to the Common and Identifier type XSDs. While extending may seem simpler, it can result in future problems when trying to reuse the java objects across nouns.

Related Concepts

WebSphere Commerce service module
Component facade interfaces
Design pattern for Process, Change and Sync service implementation
Design pattern for Get service implementation
Nouns

Related tasks

Create the component facade
Create a new search expression
Create the service command
Create the client library