Creating a new expression builder

An expression builder is used by the wcf:getData tag on a JSP file to construct an XPath expression that is used by a WebSphere Commerce service to retrieve data.

About this task

All expression builders are defined in the get-data-config.xml file. The base get-data-config.xml file for each WebSphere Commerce service module is located in \LOBTools\WebContent\WEB-INF\config\com.ibm.commerce.component\get-data-config.xml. You cannot modify this file directly. Instead, create the \LOBTools\WebContent\WEB-INF\config\com.ibm.commerce.component-ext extension folder to store the extended get-data-config.xml file.

Procedure

  1. Open WebSphere Commerce Developer.
  2. All new expression builders must be added to a custom get-data-config.xml file. Do not modify default WebSphere Commerce files. If you have not already created a get-data-config file:
    1. In the Enterprise Explorer view, navigate to LOBTools > WebContent > WEB-INF > config.
    2. Right-click config then click New Folder.
    3. In the Folder name, the text is dependent on whether you are working with your own service module or a default WebSphere Commerce service module:
      • For default WebSphere Commerce service modules, use com.ibm.commerce.component-ext. For example, com.ibm.commerce.catalog-ext
      • For your own custom service modules, use the custom service module name. No "-ext" suffix is required. For example, com.mycompany.commerce.tutorialstore
    4. Click Finish.
    5. Right-click the new folder then click New > Other > Simple > File > Next.
    6. In the File name field, enter get-data-config.xml.
    7. Click Finish. The get-data-config.xml file opens.
    8. Copy the following elements to the custom get-data-config.xml, to start the file: 
      <?xml version="1.0" encoding="UTF-8"?>
<wcf:get-data-config
xmlns:wcf="http://www.ibm.com/xmlns/prod/commerce/foundation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/commerce/foundation ../../xsd/get-data-config.xsd ">

<!-- Define data types here -->

<!-- Define client facades here -->

<!-- Define expression builders here -->

</wcf:get-data-config>
      All expression builder code is added between the these tags.
  3. If your expression builders use any custom data types, you must include a <data-type> and <client-facade> element to instruct the expression builder how to work with your data. The <data-type> element defines the Java class of your custom data type, and the <client-facade> element defines the class, and method to call on that class, to retrieve the objects. 
    <data-type>
		<name>Project</name>
		<type>com.mycompany.commerce.project.facade.datatypes.ProjectType</type>
	</data-type>
		<client-facade>
		<data-type-name>Project</data-type-name>
		<class>com.mycompany.commerce.project.facade.client.ProjectFacadeClient</class>
		<method>getProject</method>
	</client-facade>
  4. In the file editor, add one or more expression builders. An example expression builder that performs Catalog search is provided below as an example: 
    <expression-builder>
	<name>findAllCatentriesByWarrantySearchNumeric</name>
	<data-type-name>CatalogEntry</data-type-name>
	<class>
		com.ibm.commerce.catalog.internal.client.taglib.util.CatalogSearchExpressionBuilder
	</class>
	<method>formatExpression</method>
	<param>
		<name>template</name>
		<value>
			/CatalogEntry[(@catalogEntryTypeCode='$catEntryTypes$') and search(UserData/UserDataField/Warterm='$warterm$' or contains(UserData/UserDataField/Wartype,'$wartype$') or contains(Description/Attributes/careinstruction,'$careinstruction$'))]
		</value>
	</param>
	<param>
		<name>accessProfile</name>
		<value>MyCompany_All</value>
	</param>
</expression-builder>
    The meanings of the XML elements are described in the following list:
    name
    The name of the expression builder. The wcf:getData tag in the controller JSP file refers to this name.
    data-type-name
    The name of the data type with which this expression builder definition will be associated. In the example the expression builder is defined for a search that is associated with CatalogEntry
    class
    The fully qualified Java class name of the expression builder. The default is used in the example for Catalog search.
    method
    The method name of the expression builder. This method must accept a java.util.Map and return an instance of com.ibm.commerce.oagis9.datatypes.ExpressionType. The default is used in the example.
    param
    The param element is used to declare parameters that are expected by the expression builder. It is assigned by name and value These child nodes define a parameter to be passed to the query template file.
    template
    The search template used to generate the XPath key and locate the SQL statement in the query template file.
    accessProfile
    Each expression builder is associated with a specific Access Profile. This Access Profile, together with the XPath query defined above, uniquely identifies a query in the query template file.
    Note: The data service layer has a specialized convention for UserData in the search mapping, as /UserData/UserDataField/Warterm is not valid XPath. This notation is used to represent the value of the Warterm and Wartype attributes in the UserData field in the example.
  5. Save and close the file.