Creating and customizing REST services with the BOD mapping framework

HCL Commerce provides a Java Emitter Template (JET) called the JET RESTful Resource pattern as part of the BOD mapping framework. The JET RESTful Resource pattern generates a JAX-RS annotated Java class that provides REST service for a specific resource. To generate these files, you must create a pattern input file that contains specifications that are required to implement the REST service by using a BOD noun.

Prerequisites for using the JET RESTful Resource pattern

The JET RESTful Resource pattern works on the Eclipse Modeling Framework (EMF) and uses the Java Emitter Templates (JET) to generate the source code. Ensure that EMF with JET is installed in your development environment before you begin.

Ensure that you install the JET package within your HCL Commerce Developer environment. For more information, see Installing the Java Emitter Template (JET) package.

Ensure that the following plug-in IDs are installed:

org.eclipse.emf.codegen
com.ibm.commerce.toolkit.internal.pattern.rest

Format of the pattern input file

Pattern input files provide the required information to the JET RESTful Resource pattern in the following format:


<rest 
   componentName="component_name" 
   packageNamePrefix="package_name_prefix">
  <noun 
        name="noun_name" 
        pluralNounName="plural_noun_name" 
        resourceName="resource_name"
      actionExpression="action_expression" 
        actionExpressionSuffix="action_expression_suffix" 
        defaultAccessProfile="default_access_profile" 
        defaultExpression="default_get_xpath_expression">
       <findBy 
         expression="get_xpath_expression" 
         name="findby_name"
         accessProfile="get_access_profile"/>
       <delete 
         key="key_to_delete" 
         method="delete_method"/>
       <create 
         for="create_for" 
         method="create_method"/>
   <update 
         for="update_for" 
         method="update_method"/>
  </noun>
</rest>

Note: The resourceName does not have to match the noun name in a pattern input XML file. Ensure that the resourceName you specify does not match any of the default REST resources.

The following table describes the variables in the pattern input XML file:


Input file variable	Required	Description
`component_name`	Yes	The name of the component that contains the Web service from which you want to create a REST service. If you are using an existing HCL Commerce service, obtain the component name by viewing the list in this topic: HCL Commerce Web services Examples of component names are: Catalog Marketing Order If you are creating a REST service from a custom HCL Commerce Web service, use the name of the component that contains the custom Web service.
`package_name_prefix`	Yes	The prefix of the package that contains the Java class output by this pattern. For a REST service from an HCL Commerce noun, use `com.ibm.commerce` For a REST service from a custom noun, use `com.your_company_name.commerce`, for example, `com.mycompany.commerce`
`noun_name`	Yes	The name of the noun you want to use to implement the REST service. To view nouns available for HCL Commerce components, see HCL Commerce Web services.
`plural_noun_name`	Yes	The plural form of the noun you want to use to implement the REST service. The convention is to specify the same singular value in a RESTful URL. For example, if a noun is Person, both `noun_name` and `plural_noun_name` should be set to be Person.
`resource_name`	No	The name of the REST resource you want to specify for a REST service.
`action_expression`	No	The action expression for the noun or its sub noun. For example: `AddressBook/Contact`.
`action_expression_suffix`	No	The action expression suffix for the noun or its sub noun. For example: `[1]`.
`default_access_profile`	Yes	The name of the default storefront access profile to use for the HCL Commerce service request. The access profile defines the data to include in the response. Access profiles are defined for each noun in HCL Commerce Web services. Typically, storefront access profiles start with `IBM_Store` instead of `IBM_Admin`.
`default_get_xpath_expression`	No	The XPath expression for the GET service that gets all instances of a noun, rather than returning a specific instance of the noun by its identifier. Include this parameter in your pattern input file only if you need the JAX-RS resource to get all instances of a noun. For example, the Catalog noun has a GET XPath expression that gets all the sales catalogs for the store. In this case, the attribute in the pattern input file is: `defaultExpression="/Catalog[@primary='false']"` If your RESTful URL does not include an identifier, the JAX-RS resource uses the `default_get_xpath_expression`.
`get_xpath_expression`	Yes 1	The XPath expression for the GET service that gets a noun by using the internal or external identifier you specified in the URL in the previous procedure. Example of an XPath expression that uses an internal identifier-Get Catalog service: `/Catalog[CatalogIdentifier[(UniqueID=)]]` This XPath expression gets a catalog by its unique ID and returns the catalog that matches the ID. Important: When you are including the XPath expression in the pattern input file, specify the following characters for the numeric UniqueID value, regardless of what is in the documented XPath expression: `{0}` The previous example XPath expression must look like the following string in the pattern input file: `/Catalog[CatalogIdentifier[(UniqueID={0})]]` Note: HCL Commerce does not provide a RESTful Web service for the Catalog noun, but you could create one using the procedures in this section. Example of an XPath expression that uses an external identifier-Get MarketingSpotData service: `/MarketingSpotData[MarketingSpotIdentifier[ExternalIdentifier[(Name=)]]]` This XPath expression gets e-Marketing Spot data by its external identifier (in this case, its name) and returns the data for display to a customer. Important: When you are including the XPath expression in the pattern input file, if the identifier value is a string, specify the following characters for the string value, regardless of what is in the documented XPath expression: `\"{0}\"` The previous example XPath expression must look like the following string in the pattern input file: `/MarketingSpotData[MarketingSpotIdentifier[ExternalIdentifier[(Name=\"{0}\")]]]`
`findby_name`	Yes 1	The suffix of the method name that is called when the URL contains an identifier. The pattern creates a method by using this suffix for the name. In the generated Java class, the full method name is `findByfindby_name`. The `findby_name` should match the identifier specified for the XPath expression for the Get service. For example, for the Get Catalog XPath expression in the previous row, an appropriate `findby_name` is `Id`.
`get_access_profile`	Yes 1	The name of the access profile to use for the HCL Commerce service get request. The access profile defines the data to include in the response.
`key_to_delete`	Yes 1	The unique key or identifier to delete a resource in an HCL Commerce service.
`delete_method`	Yes 1	The delete method of an HCL Commerce service client façade class, which takes `Map` as parameter. For example: `MemberFacadeClient.deleteAddressForPerson(java.util.Map)`.
`create_for`	Yes 1	The resource to be created by using an HCL Commerce service.
`create_method`	Yes 1	The create method of an HCL Commerce service client façade class, which takes `Map` as parameter. For example: `MemberFacadeClient.addAddressForPerson(java.util.Map)`.
`update_for`	Yes 1	The resource to be updated by using an HCL Commerce service.
`update_method`	Yes 1	The update method of an HCL Commerce service client façade class, which takes `Map` as parameter. For example: `MemberFacadeClient.updateAddressForPerson(java.util.Map)`.

Note: 1 These variables are required if the respective actions (findBy, create, update, and delete) are defined. At least one action definition is required for the noun. Multiple nouns and actions are supported in the input XML pattern file. The input XML pattern file must contain unique values for noun name, key, for, and method names.

Sample pattern input file

This example input file generates the Java classes and properties files that are required to work with the Member service to create, update, retrieve, and delete the available resources:


<rest 
   componentName="Member" 
   internal="false" 
   packageNamePrefix="com.ibm.commerce">
  <noun 
       name="Person" 
       pluralNounName="Person" 
       resourceName="Person"
     actionExpression="AddressBook/Contact" 
       actionExpressionSuffix="" 
       defaultAccessProfile="IBM_Store_Details" 
       defaultExpression="{self=true}/Person">
    <findBy 
      expression="/Person[PersonIdentifier[(UniqueID={0})]]" 
      name="UniqueID" 
      accessProfile="IBM_Store_Details"/>
    <findBy 
      expression="/Person[Credential[LogonID={0}]] " 
      name="LogonID" 
      accessProfile="IBM_Store_Details"/>
    <delete 
      key="ContextAttribute" 
      method="deleteContextAttributeForPerson"/>
    <create 
      for="Person" 
      method="registerPerson"/>
    <update 
      for="Person" 
      method="updatePerson"/>
  </noun>
</rest>

Generating the source code

Perform the following steps to generate the source code for REST services:

Create an XML file under the customization project/location (WebSphereCommerceServerExtensionsLogic) directory and copy sample input file into it. Make your required changes to the file according to the input specifications table from the Format of the pattern input file section.
Save your changes to the file. Then, right click the file and select Run As > Run Configuration.
Select Jet Transformation, then right click and select New. Anew configuration is created.
The generated XML file appears in the Transformation Input section. Select the transformation ID as com.ibm.commerce.toolkit.internal.pattern.rest:
Select Apply > Run to start the transformation.
After successfully running the transformation, the output files are generated under the WebSphereCommerceServerExtensionsLogicproject.
Check for any compilation errors in Java classes, which might occur because of any missing JAR files in the classpath, and rectify them.

Location of the pattern output file

The pattern generates files in the following directories:

Resource handler classes: src\package_name.rest.extension.resource_name.handler
Resource helper classes: src\package_name.rest.extension.bod.helpers
BOD mapping XML files: WebContent\WEB-INF\config\bodMapping-ext
Service client library XML file: WebContent\WEB-INF\config\bodMapping-ext
Resource properties file: WebContent\WEB-INF\config
Resource configuration XML file: WebContent\WEB-INF\config\com.ibm.commerce.rest-ext

Consuming the generated code

Perform the following steps to consume the generated code for customization:

Copy the rest-resource_name-clientobjects.xml file to the similar location under the Rest project in your workspace. Add additional XPath to attribute mappings for the noun you selected in the input XML file. The XPath is populated to the response data against the mapped attributes.
Copy the resources-ext.properties file to the similar location in the Rest project or merge the entries of files for the newly added resource handler class.
Copy the wc-rest-resourceconfig.xml file to the similar location in the Rest project. Create the WEB-INF\config\com.ibm.commerce.rest-ext folder if it does not already exist.
Copy the wc-service-client-library.xml file to the similar location in the Rest project or merge the entries of files for the newly added resource handler class.

Testing the customization

Restart the test server and invoke the URI for the newly added resource handler class.

The URI should resemble the following address:

For a Get request (Person from the context):

http://host_name/wcs/resources/store/10101/person

For a Get request (Person with logon ID):

http://host_name/wcs/resources/store/10101/person/byLogonId/personID