Retrieving objects by transforming Nouns

The Management Center sends Uniform Resource Locator (URL) requests and receives XML-formatted Management Center objects, whereas the WebSphere Commerce services send and receive BOD messages. The Management Center Web application mediates messages between the Management Center and WebSphere Commerce. Requests that are sent from the Management Center are transformed into the appropriate BOD requests of the WebSphere Commerce service and the responses of those BOD requests are transformed into the XML representation that the Management Center understands. The steps that are required to transform messages differs based on the type of message.

About this task

When data is sent from the WebSphere Commerce Server to the Management Center, the Management Center Web application transforms Nouns into the XML representation that is expected by the Management Center. The JavaServer Pages (JSP) file that represents the Struts action forward is used to transform Nouns into XML format.

Procedure

  1. Open WebSphere Commerce Developer and switch to the Enterprise Explorer view.
  2. In the Enterprise Explorer view, expand LOBTools > WebContent > WEB-INF > config
  3. Create a directory named com.mycompany.commerce.project.
  4. Create a XML file that is named, get-data-config.xml, under the newly created directory.
  5. All primary data types, client facade classes, and expression builders that are used in JSP tags are included within an XML configuration file. Copy get-data-config.xml to overwrite the newly created file. The file is also shown in the following code sample:
    <?xml version="1.0" encoding="UTF-8"?>
    
    <!--
     =================================================================
      Licensed Materials - Property of IBM
    
      WebSphere Commerce
    
      (C) Copyright IBM Corp. 2008 All Rights Reserved.
    
      US Government Users Restricted Rights - Use, duplication or
      disclosure restricted by GSA ADP Schedule Contract with
      IBM Corp.
     =================================================================
    -->
    <_config:get-data-config 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/get-data-config.xsd ">
    
    	<data-type>
    		<name>Project</name>
    		<type>com.mycompany.commerce.project.facade.datatypes.ProjectType</type>
    	</data-type>
    	<data-type>
    		<name>ProjectCollection</name>
    		<type>com.mycompany.commerce.project.facade.datatypes.ProjectCollectionType</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>
    	<client-facade>
    		<data-type-name>ProjectCollection</data-type-name>
    		<class>com.mycompany.commerce.project.facade.client.ProjectFacadeClient</class>
    		<method>getProjectCollection</method>
    	</client-facade>		
    	
    
    	<!-- Project Collection services -->
    	<expression-builder>
    		<name>getAllProjectCollections</name>
    		<data-type-name>ProjectCollection</data-type-name>
    		<expression-template>{_wcf.ap=$accessProfile$}/ProjectCollection</expression-template>
    		<param>
    			<name>accessProfile</name>
    			<value>MyCompany_Admin_Details</value>
    		</param>		
    	</expression-builder>
    	
    	<expression-builder>
    		<name>findProjectCollectionsBasicSearch</name>
    		<data-type-name>ProjectCollection</data-type-name>
       <class>com.ibm.commerce.foundation.internal.client.taglib.util.SearchExpressionBuilder</class>
    	  <method>formatExpression</method>		
    		<param>
    			<name>template</name>
    			<value>/ProjectCollection[search(ProjectCollectionIdentifier/ExternalIdentifier/Name='$name$')]</value>
       </param>		
    		<param>
    			<name>accessProfile</name>
    			<value>MyCompany_Admin_Details</value>
    		</param>		
    	</expression-builder>	
    	
    	<!-- Project services -->
    	<expression-builder>
    		<name>getProjectsByCollection</name>
    		<data-type-name>Project</data-type-name>
    		<expression-template>{_wcf.ap=$accessProfile$}/Project[Collection[ProjectCollectionIdentifier[(UniqueID='$collectionId$')]]]</expression-template>
    		<param>
    			<name>accessProfile</name>
    			<value>MyCompany_Admin_Summary</value>
    		</param>		
    	</expression-builder>
    
    	<expression-builder>
    		<name>getUnassignedProjects</name>
    		<data-type-name>Project</data-type-name>
    		<expression-template>{_wcf.ap=$accessProfile$}/Project[Unassigned]</expression-template>
    		<param>
    			<name>accessProfile</name>
    			<value>MyCompany_Admin_Summary</value>
    		</param>		
    	</expression-builder>
    
    	<expression-builder>
    		<name>getProjectCollectionReference</name>
    		<data-type-name>Project</data-type-name>
    		<expression-template>{_wcf.ap=$accessProfile$}/Project[ProjectIdentifier[(UniqueID='$projectId$')]]</expression-template>
    		<param>
    			<name>accessProfile</name>
    			<value>MyCompany_Admin_ProjectColRel</value>
    		</param>		
    	</expression-builder>
    	
    	<expression-builder>
    		<name>getProjectMaterial</name>
    		<data-type-name>Project</data-type-name>
    		<expression-template>{_wcf.ap=$accessProfile$}/Project[ProjectIdentifier[(UniqueID='$projectId$')]]</expression-template>
    		<param>
    			<name>accessProfile</name>
    			<value>MyCompany_Admin_ProjectMaterial</value>
    		</param>		
    	</expression-builder>
    	
    	<expression-builder>
    		<name>getProjectInstruction</name>
    		<data-type-name>Project</data-type-name>
    		<expression-template>{_wcf.ap=$accessProfile$}/Project[ProjectIdentifier[(UniqueID='$projectId$')]]</expression-template>
    		<param>
    			<name>accessProfile</name>
    			<value>MyCompany_Admin_ProjectInstruction</value>
    		</param>		
    	</expression-builder>
    
    	<expression-builder>
    		<name>getProjectTool</name>
    		<data-type-name>Project</data-type-name>
    		<expression-template>{_wcf.ap=$accessProfile$}/Project[ProjectIdentifier[(UniqueID='$projectId$')]]</expression-template>
    		<param>
    			<name>accessProfile</name>
    			<value>MyCompany_Admin_ProjectTool</value>
    		</param>		
    	</expression-builder>
    
    	<expression-builder>
    		<name>findProjectsBasicSearch</name>
    		<data-type-name>Project</data-type-name>
    		<class>com.ibm.commerce.foundation.internal.client.taglib.util.SearchExpressionBuilder</class>
    	    <method>formatExpression</method>		
    		<param>
    			<name>template</name>
    			<value>/Project[search(ProjectIdentifier/ExternalIdentifier/Name='$name$')]</value>
            </param>
    		<param>
    			<name>accessProfile</name>
    			<value>MyCompany_Admin_Summary</value>
    		</param>		
    	</expression-builder>
    		
    </_config:get-data-config>
    There are three main parts in get-data-config.xml:
    • The data type element declares a supported data type for the getData action.
    • The client-facade element declares the component client facade that invokes the service to fetch the data.
    • The expression-builder handles building the XPath expression with the published input parameters.
    Each expression builder has the following properties:
    • The <name> node uniquely identifies the expression builder, and is used by getData tags in the project JSPs when you refer to an expression builder.
    • The <data-type-name> node contains the noun type that is returned by this expression builder.
    • The <expression template> node refers to an XPath query defined in the project query template file, which is used to retrieve specific information from the database. Parameters such as $projectID$ can be passed to the expression builder by a getData tag.
    • Each <param> node contains a pair of <name> and <value> child nodes that define a parameter to be passed to the query template file. Each expression builder is associated with a specific Access Profile. This Access Profile, together with the XPath query previously defined , uniquely identifies a query in the query template file.
  6. There are two types of JSP files that perform transformations, controller JSP files and serialization JSP fragments. Controller JSP files create, send, and receive BOD messages from the WebSphere Commerce server. Serialization JSP fragments transform Nouns to XML.
    Each object has several wcfGetChildrenService and wcfGetReferenceService to retrieve child objects and reference objects. For example, you define three instances of wcfGetChildrenService to retrieve ingredients, instructions, and associations of a recipe when you define one of the following file:
    • WebSphere Commerce Version 7.0.0.0Feature Pack 1recRecipePrimaryObjectDefinition
    • Feature Pack 3Feature Pack 2Recipe primary object definition
    Each service definition requires the value that is set for the URL property, which is mapped to a controller JSP by using Struts action configurations. The controller JSP files use the wcf:getData tag to create, send, and receive BOD objects from the WebSphere Commerce Server. The objects are parsed by serialization JSP fragments to be transformed from Nouns to XML. The XML works as a data set for property view classes.

    In this step of the lesson, you create new JSP files to transform the Noun to the OpenLaszlo object:

    1. In the Enterprise Explorer view, expand LOBTools > WebContent > jsp
    2. Create a folder named mycompany, and a new subfolder named recipe under mycompany.
    3. Import all JSP and JSP fragment files that are in the TutorialSource\LOBTools\WebContent\jsp\mycompany\recipe directory into the newly created directory, where TutorialSource is the location where you extracted the attached source code.
      The following code samples are provided as a reference:
      GetRecipesByRecipeId.jsp
      This example is a controller JSP file. It creates, sends, and receives BOD messages from the WebSphere Commerce Server.
      <?xml version="1.0" encoding="UTF-8"?>
      <%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
      <%@ taglib uri="http://commerce.ibm.com/foundation" prefix="wcf"%>
      
      <wcf:getData
      	type="com.mycompany.commerce.project.facade.datatypes.ProjectType[]"
      	var="projects" expressionBuilder="getProjectsByprojectId"
      	varShowVerb="showVerb">
      	<wcf:contextData name="storeId" data="${param.storeId}" />
      	<wcf:param name="projectId" value="${param.recipeId}" />
      </wcf:getData>
      
      <c:forEach var="project" items="${projects}">
      	<c:set var="recipeOwningStoreId"
      		value="${project.projectIdentifier.externalIdentifier.storeIdentifier.uniqueID}" />
      	<c:set var="objectType" value="Recipe" />
      	<jsp:directive.include file="serialize/SerializeRecipe.jspf" />
      </c:forEach>
      SerializeRecipe.jspf
      This file is a serialization JSP fragment. It formats Nouns from the controller JSP into XML format.
      <%@ taglib uri="http://java.sun.com/jsp/jstl/functions" prefix="fn"%>
      <object objectType="${objectType}">
        <objectStoreId>${recipeOwningStoreId}</objectStoreId>
      	<recipeId>${project.projectIdentifier.uniqueID}</recipeId>
        <name><![CDATA[${project.projectIdentifier.externalIdentifier.name}]]></name>
      	<time>${project.timeToComplete}</time>
        <difficulty>${project.difficulty}</difficulty>
      	<c:forEach var="description" items="${project.description}">
      		<object objectType="RecipeDescription"> <lDesc><![CDATA[${description.longDescription}]]></lDesc>
      			<sDesc><![CDATA[${description.shortDescription}]]></sDesc> <languageId>${description.language}</languageId>
      		</object>
      	</c:forEach>
      </object>
    Note: The XML format and JSP files have the following characteristics:
    • The XML format must begin with <?xml version="1.0" encoding="UTF-8"?> to ensure multilingual support.
    • The XML format must contain dynamic values only. Define all constant values in the Management Center.
    • All Management Center objects must have only one property that uniquely identifies the object. Although the object can be uniquely identified with two properties, the Management Center can use only one property. For information about defining Management Center objects, see Object definitions.
    • The names of the JSP files must follow the existing naming conventions to indicate the purpose of the JSP file. For example, GetRecipeByCollection.jsp.
    • The result set that is returned when multiple objects are returned for Find services must be wrapped in the objects document.
      
      <objects recordSetReferenceId="${show.recordSetReferenceId}" 
      recordSetCompleteIndicator="${show.recordSetCompleteIndicator}"
      recordSetTotal="${show.recordSetTotal}" 
      recordSetCount="${show.recordSetCount}" 
      recordSetStartNumber="${show.recordSetStartNumber}">
      
      For more information about Get result paging, see Get Request and the Show Response.