Customizing entity providers for REST services

In this lesson, you extend the default JAX-RS resource handlers to customize your REST services to support new custom response formats. By default, the WebSphere Commerce REST framework supports JSON and XML formats.

About this task

The RestfulServiceSource.zip compressed file that you downloaded in the introduction to this tutorial includes the sample code that is used to demonstrate this customization.

Procedure

  1. Add an entity provider to support the custom response format of media type "text/html". This format can be used to display results as a simple HTML web page.
    1. Open WebSphere Commerce Developer and switch to the Enterprise Explorer view.
    2. In the WebSphereCommerceServerExtensionsLogic project, create a class that is called com.mycompany.commerce.foundation.rest.providers.CustomTextHTMLEntityProvider, where com.mycompany.commerce is the name of the package where you created your REST services. Your new class must extend the com.ibm.commerce.foundation.rest.providers.AbstractEntityProvider class.
    3. Add the following code to the entity class to register the entity provider for the "text/html" response format in the JAX-RS resource handlers. 
      @Produces(value = { "text/html " })
      For an example of a complete entity handler class, see the sample class that is provided in the RestfulServiceSource.zip compressed file that you downloaded in the tutorial introduction. The sample class contains inline comments to help you implement your own entity provider.
    4. After you completed creating your class, save and close the file.
    5. Add the entity provider class name in the Rest/WebContent/WEB INF/config/providers-ext.properties file to register the new entity provider.
    6. Save and close the file.
  2. Add a response format shortcut for the custom response format, "text/html". Response format shortcuts are requested media type shortcuts that can be easily specified by a client in the request URL as a query parameter.
    For example,

    http://host_name/wcs/resources/store/{storeId}/project/byProjectId/{projectId}?responseFormat={shortcut}

    1. Open the Rest/WebContent/WEB-INF/config/com.ibm.commerce.rest-ext/wc-rest-responseformat.xml file for editing.
    2. Add the following code snippet to the file to add the shortcut for the "text/html" response format. 
      
<responseFormatMappings>
  <!-- Define response format and Internet media type mapping. -->
  <!-- Internet media type was originally called a MIME type. -->
  <!-- When default attribute is defined to true, the response format is the default format -->
  <formatMapping responseFormat="custom" mediaType="text/html"/>
</responseFormatMappings>
    3. Save and close the file.
  3. Implement new JSP files to format the data objects into the custom response format.
    1. Go to the Rest/WebContent/jsp/commerce/project/custom directory and create two JSP files to format the data object. Name the files SerializeShowProjectDataAreaTypeCustom.jsp and SerializeShowProjectCollectionDataAreaTypeCustom.jsp.

      The JSP file coding guideline is identical to the storefront JSP files that format a data object. For more an example of the contents of the JSP file, see the sample JSP files within the RestfulServiceSource.zip compressed file.

    2. After you completed creating your files, save and close the files.
    3. Add the following struts actions to the Rest/WebContent/WEB-INF/struts-extension.xml struts configuration file to register the two new JSP files. 
      
<action path="/ShowProjectCustom/0" 
 forward="/jsp/commerce/project/custom/SerializeShowProjectDataAreaTypeCustom.jsp"/>

<action path="/ShowProjectCollectionCustom/0" 
 forward="/jsp/commerce/project/custom/SerializeShowProjectCollectionDataAreaTypeCustom.jsp"/>
      Note: For more information about the struts extension configuration, see AbstractEntityProvider
    4. Save your changes and close the file.
  4. Implement a new error JSP file for the custom response format. When an error is encountered, the REST framework uses the error JSP file specific to the response format, passing in the appropriate error parameters.
    1. Go to the Rest/WebContent/jsp/commerce/project/custom directory and create a JSP file to use as the error JSP file. Name the file Error.jsp.

      For more an example of the contents of this JSP file, see the sample JSP file within the RestfulServiceSource.zip compressed file.

    2. Save and close the file.
    3. Add the following struts action to the Rest/WebContent/WEB-INF/struts-extension.xml struts configuration file to register the new JSP file. 
      <action path="/ErrorCustom/0" forward="/jsp/commerce/project/custom/Error.jsp"/>
    4. Save and close the file.
  5. Test the customization entity providers for REST services. To test the entity providers, you must invoke the URL for the Project noun and Project Collection noun.
    • Project noun URL

      http://host_name/wcs/resources/store/{storeId}/project/byProjectId/{projectId}?responseFormat=custom

    • Project Collection noun URL

      http://localhost/wcs/resources/store/{storeId}/projectcollection/byProjectCollectionId/{projectcollectionId}?responseFormat=custom

    Where storeid, projectid, and projectcollectionId is the value that is specific to your environment.
    1. Restart the WebSphere Commerce Test Server.
    2. Open a browser (Firefox) and enter the URL for the Project or Project Collection.

      Depending upon how you customized your response format JSP

      Response format JSP