Tutorial: Creating a BOD service module

In this tutorial, you develop a project service module. The services that are provided by the module are Get and Change. As a part of creating the service module, you design the logical model (a noun) and physical model (a database schema) based on your business requirement.

The Project BOD service module stores and retrieves data, and provides logic to perform operations on a business object or logical model, referred to as a noun. The noun that you define in this tutorial is called the Project noun.

This tutorial provides one example, however you can use the methods described to implement any business logic.

Previous versions of HCL Commerce relied upon the Specification and Description Language (SDL) for creating service modules. Since Version 9 uses the Java Persistence API, this tutorial shows how to use BOD to call the JPA in HCL Commerce. In order to reduce complexity and emphasize how JPA operations work in Version 9, the tutorial will define a single table and noun.

Any service that uses an XML schema requires a logical model definition. For HCL Commerce, the logical model is represented as nouns and noun parts. Nouns are the business objects in your application. Noun parts are parts of those objects that are given distinct names so that they can be handled independently of the noun. Nouns define the name of each data element in the logical model, and assign that name to a data type. This data type can be a primitive XML schema type such as a boolean, or it can be a complex type that is constructed of data elements. For example, ProjectExternalIdentifierType contains Name (represented by a string type) and StoreIdentifier (represented as a _wcf:StoreIdentifierType). _wcf:StoreIdentifierType is a predefined complex type construct that can be shared among all of the nouns. It is defined in the IdentifierTypes.xsd file. HCL Commerce provides some predefined complex type constructs, which are shared among all of the nouns. To use the common predefined type constructs, you need to import the file in the Project.xsd file. The following code sample shows how to import these type constructs.
<import namespace="http://www.ibm.com/xmlns/prod/commerce/9/foundation"
schemaLocation="../../../../IBM/Commerce/Resources/Components/IdentifierTypes.xsd" />
Note: To reduce complexity, HCL Commerce uses its own simplified nouns, defined types, and primitive XML schema types, rather than using the nouns and base types provided by OAGIS.

The service module that you create in this tutorial contains one noun: Project. For this tutorial, these Project nouns are predefined for you. The Project.xsd file, which defines the nouns, is provided as part of the ProjectServices.zip sample file.

For this tutorial, the definitions of the noun contain information that is listed in the table for each noun. The tables list the access profiles that include the information. Data included in the Summary profile are shown in the summary view, and data included in the Details profile are shown in the details view.

Project noun

The Project noun represents the logical data model of the new service module that you create. The definition of this logical model is a key development step as this model is exposed to any client that uses the Project service. The model is also extensively used in the BOD programming model for the business logic layer of HCL Commerce. The following diagram shows the schema definition for the Project noun:
The following diagrams show the structure for Project noun:
To manage the Project noun information that you create in this tutorial, you implement Get, and Change services for the new service module.
Get services
You can use the Get service to retrieve Project noun information that is based on an XPath search expression. This tutorial demonstrates how to support the following XPath expressions:
 Find Project by Project UniqueID:
        /Project[ProjectIdentifier[(UniqueID='10001')]]
Change services
The Change service updates project information for a Project noun. The Change service can update the projectName(you can wrote add and delete service by yourself).

Learning objectives

After completing this tutorial, you should be familiar with the following concepts:
  • The HCL Commerce BOD command framework
  • Extension and customization tasks.
  • Logical model definitions.
  • The Java Emitter Template.
  • Service Data Objects.
  • Eclipse Modeling Framework.
  • The JPA Framework
  • The Business Object Mediator.
After completing this tutorial, you should be able to perform the following tasks:
  • Create an extended sites store with a custom catalog.
  • Review the Project noun.
  • Customize the physical layer.
  • Generate the base code for your Project service module.
  • Add language-specific exception messages to the properties files.
  • Import mediators.
  • Configure the data service layer for the Project service module.

Time required

Expect this tutorial to take two hours to complete. The tutorial takes longer if you explore concepts that are related to this tutorial.

Skill level

This tutorial is intended for advanced HCL Commerce developers who are responsible for creating and customizing HCL Commerce services. To complete this tutorial, ensure that you are familiar with the following terms and concepts:
  • Java programming language
  • XPath
  • XSD
  • Web services
  • XML
  • HCL Commerce services
  • JPA Framework
  • Nouns
  • Relational databases
  • SQL

System requirements

Before you begin this tutorial, ensure that you completed the following tasks:

Tutorial resources

To complete this tutorial, the following resources are used. Ensure that you download and extract the following compress file to a temporary directory, such as C:\Temp before you begin this tutorial:
Note: If you are completing this tutorial as a prerequisite for the Management Center customization tutorial, "Adding a tool to the Management Center", you can import the projects within the following Recipe_service_source.zip compressed file into your development environment. These files include the source code for the completed BOD service module for the sample recipe services. If you want to learn more about creating a service module, however, you are recommended to complete the tutorial in full instead of importing these projects.

If you do import these projects, you must still complete the step to update the build dependencies for the service module. For more information, see Generating the Project service module projects.