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:
  1. 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.
  2. Save your changes to the file. Then, right click the file and select Run As > Run Configuration.
  3. Select Jet Transformation, then right click and select New. Anew configuration is created.
  4. The generated XML file appears in the Transformation Input section. Select the transformation ID as com.ibm.commerce.toolkit.internal.pattern.rest:
    Run Configurations
  5. Select Apply > Run to start the transformation.
  6. After successfully running the transformation, the output files are generated under the WebSphereCommerceServerExtensionsLogicproject.
  7. 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:
  1. 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.
  2. 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.
  3. 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.
  4. 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):
  1. http://host_name/wcs/resources/store/10101/person
For a Get request (Person with logon ID):
  1. http://host_name/wcs/resources/store/10101/person/byLogonId/personID