Gift Center for Consumer direct sample store:Creating a new IBM Gift Center action

Samples > Sample stores > Consumer direct sample store > IBM Gift Center for the Consumer direct sample store > IBM Gift Center > Customize the Web (presentation) layer

Create a new IBM Gift Center action

A gift registry action is a normal Struts action. For details on creating and configuring a Struts action, refer to the Apache Struts documentation. The following steps are specific to creating IBM Gift Center actions:
Create a new service mapping group for the new action. This mapping group can be added to a service mapping file, which can be found under the following directory: /xml/config/giftcenter/service_mapping_config.xml A service mapping group describes, for a given action, how incoming name-value pairs can be translated to a BOD. It contains a set of service mappings. Each service mapping describes how a URL request parameter can be mapped to a node in a BOD's value object. For example, the following mapping group indicates that the Struts action GiftRegistryItemDelete will invoke the service updateGiftRegistry. The verb used for this service will be UpdateVerb, and all the request parameters will be mapped to some node in the noun GiftRegistryVO by default. The BOD to be used is UpdateGiftRegistryBOD. The parameter called externalId corresponds to the externalId in the first GiftRegistryVO found in the list of the nouns.
<MappingGroup name="GiftRegistryItemDelete" 
        service="updateGiftRegistry" 
        verbType="com.ibm.commerce.component.bod.UpdateVerb" 
        defaultNounType="com.ibm.commerce.giftregistry.service.valueobjects.GiftRegistryVO" 
        serviceInputType="com.ibm.commerce.giftregistry.service.businessobjects.UpdateGiftRegistryBOD">        
<Mapping source="externalId" target="nouns[1]/externalId"/>        
<Mapping source="giftRegistryId" target="nouns[1]/giftRegistryId"/>        
<Mapping source="giftItemId" target="nouns[1]/giftItems[1]/giftItemId"/>        
<Mapping source="memberId" target="nouns[1]/giftItems[1]/memberId"/>        
<Mapping source="partNumber" target="nouns[1]/giftItems[1]/partNumber"/>
</MappingGroup> 
The "source" attribute in a service mapping must be a request parameter name. The "target" attribute in a service mapping is an XPath expression that points to a node in a value object.
Here is another example:
<Mapping source="externalId_$index" target="nouns[$index]/externalId"/>
This mapping indicates that the externalId request parameter indexed by $index will be corresponding to the externalId property in the value object that can be located in the nouns list with the same index. That is, assuming the registryBOD is the BOD instance that contains this mapping, registryBOD.getDataArea().getNounsArray()[0] .getExternalId() will return the value of externalId_1.
Create an entry for an action form in the struts-config-GiftCenter.xml file. If a request parameter for an action can be directly mapped to a node in a value object, then you can simply use com.ibm.commerce.giftregistry.struts.GiftRegistryBaseValidatorActionForm as the form class. This form must be the base form for all the gift center action forms. It performs IBM Gift Center related validation, and converts any request parameter that has an associated mapping into some value in the resultant BOD instance. It is possible that further process is needed before the mapping takes place. For instance, a GiftRegistryItemVO accepts only partNumber and memberId as item identifiers, but a request parameter may contain a catentryId only. In this case, partNumber and memberId must be resolved, and then they must be put into the request properties before mapping starts. Next, create a new action form that extends GiftRegistryBaseValidatorActionForm. In this new form, you can choose any of the following three methods to overwrite:
updateMappingInput(): you can overwrite this method if you simply want to update request properties for mapping. In the example above regarding catentryId, partNumber, and memberId, updateMappingInput() will take the catentryId, resolve to partNumber and memberId, then put the data back into the input map, which can later be used by the service mapper.
As a second example, the snippet below add a new request parameter called "myNewField" into the request properties. If this parameter is specified in the service mapping, it will be processed accordingly.
public Map updateMappingInput(ActionMapping mapping, 
        HttpServletRequest request, Map inMap) throws ECException {final String 
        methodName = "updateMappingInput";         GiftRegistryTraceLogger.entry(this, methodName);         // Make sure changes introduced by the super is preserved 
        inMap = super.updateMappingInput(mapping, request, inMap);         return inMap.put("myNewField", "abc");         }
validate(): You can overwrite this method if add more validation logic.

getServiceMappingResult(): This method processes all the request properties, and then returns the resultant BOD instance. Overwrite this method with care if overwriting updateMappingInput() is not enough. If you plan to overwrite the method getServiceMappingResult(), manually convert or create a MappingResult object from the given parameters.
Create an entry for the new Struts action in the struts-config-GiftCenter.xml file. If an existing IBM Gift Center action can accomplish the job, you can simply specify that action class as the class of this new action. For example, the GiftRegistryCreate action is actually a special case of GiftRegistryUpdate, so you can use GiftRegistryUpdateAction to create gift registries with the help of a set of mappings specific to creating registries. If you need new functionality, such as post-processing service responses, create a Struts action class that extends one of the IBM Gift Center action classes. All IBM Gift Center action classes should extend GiftRegistryBaseAction. You can choose any of the two methods to overwrite:

invokeService(): this method delegates a request to the underlying gift center services, and then collects the response data. Overwrite this method with care. You should always call super.invokeService() in the overwriting method, as the GiftRegistryBaseAction#invokeService() performs a lot of pumping work, such as collecting mapping result, and locating service.

processServiceResult(): this method allows you to update the result returned by IBM Gift Center services. For example, you can add the externalId of the newly created gift registry into the response object in this method.
Constructing a Struts action with a service request: struts-config-GiftCenter.xml
You can configure how an IBM Gift Center's Struts action constructs a service request based on incoming request parameters. Each service request is described by a BOD. A BOD has three essential elements: which service to invoke, what data to process, and how given data is processed. The service_mapping_config.xml file describes how incoming Web requests can be mapped to these elements.
Consider the following example:
<MappingGroup name="GiftRegistryItemDelete"
service="updateGiftRegistry"        
verbType="com.ibm.commerce.component.bod.UpdateVerb"
defaultNounType="com.ibm.commerce.giftregistry.service.valueobjects.GiftRegistryVO"
serviceInputType="com.ibm.commerce.giftregistry.service.businessobjects.UpdateGiftRegistryBOD"> 
   
<Mapping source="externalId"
target="nouns[1]/externalId" action="update"/>    
<Mapping source="giftRegistryId"
target="nouns[1]/giftRegistryId" />    
<Mapping source="giftItemId"
target="nouns[1]/giftItems[1]/giftItemId" />    
<Mapping source="memberId"
target="nouns[1]/giftItems[1]/memberId" />    
<Mapping source="partNumber"
target="nouns[1]/giftItems[1]/partNumber" />
</MappingGroup>
The name of this mapping group indicates that the group is for the Struts action GiftRegistryItemDelete. That is, "GiftRegistryItemDelete" must be the value of the name attribute of an "action" element in the struts-config-GiftCenter.xml file. This Struts action should invoke the "updateGiftRegistry" service, as specified in the attribute "service". This service requires a BOD of type "com.ibm.commerce.giftregistry.service.businessobjects.UpdategiftRegistryBOD", as specified in the "serviceInputType" attribute. If not otherwise specified, the type of the nouns in the BOD is "com.ibm.commerce.giftregistry.service.valueobjects.GiftRegistryVO", as specified in the "defaultNounType" attribute. The type of the verb in the BOD is "com.ibm.commerce.component.bod.UpdateVerb" as specified in the attribute "verbType".
The example illustrates that the system will convert five URL parameters. They are specified in the "source" attribute within the <Mapping> elements. The "target" attribute specifies which attribute in a value object is corresponding to the source. For example, the incoming externalId parameter is mapped to the property GiftRegistryVO's property externalId. Since the action is specified as "update", the value of the GiftRegistryVO's exernalId will be updated to the value of the "externalId" parameter.
Notes:

A "noun" here refers to the noun type of the BOD. Each target is described by XPath expression. (For details about XPath expression, refer to XPath specification on http://w3c.org).

WC-style index is also supported. For example, if you have <Mapping source="externalId_$index" target="nouns[$index]/externalId"/>, then you know externalId_1 will be corresponding to the first noun's externalId, and externalId_i will be corresponding to the i-th noun's externalId. Each <Mapping> element also supports an optional "nounType" attribute. The value of this attribute will overwrite the value of defaultNounType specified for a <MappingGroup>. The service_mapping_config.xml file can contain one or more mapping groups.

Related concepts

IBM Gift Center architecture

Related tasks

Customize the Web (presentation) layer
Extend the service interface for the gift registry

Related reference

IBM Gift Center actions

+
Search Tips | Advanced Search