Tutorials > Program model > Web services
Tutorial: Creating a new WebSphere Commerce BOD service module
Attention: This tutorial is currently under revision. The content might contain errors or inaccuracies. Subscribe to this page to be notified when an updated version is available.
In this tutorial you follow the development of a sample service module, TutorialStore, based on the concept of a Store in WebSphere Commerce version 7. The services provided by the tutorial store is Get, Change and Process.
The BOD command framework is an implementation of the business logic layer, that deals with business object documents, and their Java representation, logical service data objects (SDOs). You are implementing the Get, Change, and Process design patterns in the BOD command framework. For more information see the following topics:
- WebSphere Commerce BOD command framework
- Business Object Document Get processing pattern
- Business Object Document Change processing pattern
- Business Object Document Process processing pattern
You can use the Get service to retrieve store information based on a XPath search expression. The tutorial will demonstrate how to support the following XPath expressions:
- Find store by store ID: /TutorialStore[StoreIdentifier[UniqueID='123']]
- Find store by name: /TutorialStore[StoreIdentifier[ExternalIdentifier[NameIdentifier='MyStoreName']]]
- Retrieve all stores: /TutorialStore
The Change service updates a Store description. This tutorial implements the following change actions:
- Change a store's description: <oa:ActionExpression actionCode="Update" expressionLanguage="_wcf:XPath">/TutorialStore[1]/StoreDescription</oa:ActionExpression>
The Process service initiates a business process for the tutorial store. For this tutorial we will implement the following process actions:
- Open a store: <oa:ActionExpression actionCode="Open" expressionLanguage="_wcf:XPath">/TutorialStore[1]</oa:ActionExpression>
- Close a store: <oa:ActionExpression actionCode="Close" expressionLanguage="_wcf:XPath">/TutorialStore[1]</oa:ActionExpression>
For the purpose of this tutorial, the definition of the TutorialStore noun contains the information listed in the table below. The table displays the access profile that includes this information for the above XPath expressions:
| Data | Description | Applicable Access Profiles |
|---|---|---|
| Store identifier information | Information to uniquely identify the store. | Summary, Detail |
| Store description | Description information about the store. | Detail |
| State | Whether the store is "Open", "Closed" or "Suspended." | Summary, Detail |
| Store category | The category of the store, such as B2C or B2B. | Summary, Detail |
| Inventory system | The inventory system used by the store. | Detail |
| Store directory | The store directory that contains the file resources associated with the store. | Summary, Detail |
| Supported languages | The languages supported by the store. | Detail |
| Supported currencies | The currencies supported by the store. | Detail |
The assets created during this tutorial are represented in the following diagram. As you progress through the tutorial, we will see different versions of the diagram, with the relevant asset for the current lesson highlighted.
Learning objectives
The learning objectives for the tutorial are:
- Understand the WebSphere Commerce BOD command framework.
- Overview of simple extension and customization tasks.
Time required
This tutorial should take approximately 120 minutes to finish. If you explore other concepts related to this tutorial, it could take longer to complete.
Skill level
Advanced
Audience
This tutorial is intended for WebSphere Commerce developers who are responsible for creating and customizing WebSphere Commerce services.
System requirements
Before beginning this tutorial ensure that you have fulfilled the following prerequisites:
- Installed WebSphere Commerce v7.
- Installed WebSphere Commerce Developer v7.
- Install the Java Emitter Template (JET) package
- Set up the development environment.
- Downloaded and unzipped TutorialStore.zip to a temporary location on the hard drive.
Prerequisites
Attention: When you use RAD to generate the Java artifacts, by default EMF 2.4 is chosen.
To work with WebSphere Commerce v7, explicitly select EMF 2.2 while you generate the Java artifacts. Refer to Set an EMF genmodel to generate 2.2 compatible objects for more information. To complete this tutorial you should be familiar with the following terms and concepts:
- Web services
- XML
- WebSphere Commerce services
- Relational databases
- SQL
Lessons in this tutorial
- Define the TutorialStore noun
Any service that uses an XML schema requires a logical model definition. For WebSphere Commerce, the logical model is represented as a noun.To reduce complexity, WebSphere Commerce uses its own simplified nouns, defined types, and primitive XML schema types, rather than using the nouns and base types provided by OAGIS.
- Generate the TutorialStore service module projects
The Java Emitter Template (JET) is an Eclipse-enabled template engine for generating applications based on model-driven architecture transformations. WebSphere Commerce uses a JET plug-in for creating WebSphere Commerce service modules from a simple XML file. By describing the service module in a specialized XML syntax, the service modules can be generated. This allows you to start directly with the service module implementation without having to spend hours with the setup and configuration of a service module. - Generate the SDOs for the TutorialStore noun
Once you have the base code and project structure generated using JET, you now can generate the service data objects (SDOs) that implement the logical data model of the TutorialStore noun, which is defined in the TutorialStore.xsd file. SDOs are Java objects that represent the nouns in the logical model. You can generate these nouns from the noun definition. - Implement the persistence layer for the WebSphere Commerce BOD programming model
The BOD programming model provides a Data Service Layer that is independent of the actual physical schema. - Add language specific exception messages
In this step you add language-specific exception messages to the properties files used by mediators and commands. You will write the mediator and command code in a later lesson. - Implement Business Object Mediators to transform logical SDOs and physical SDOs
The Business Object Mediator in the WebSphere Commerce Data Service Layer transforms between logical SDOs (the Java implementation of a noun) and physical SDOs (a Java representation of a database table). There are two types of mediators: read mediators and change mediators. Read mediators transform the physical representation of data (physical SDOs) to the logical representation (logical SDOs). Change mediators translate actions on the logical SDOs (such as create, update, and delete) into operations on the physical data. - Configure the data service layer for the TutorialStore service module
In this lesson we will configure the data service layer for the TutorialStore service module. - Implement the business logic layer
This lesson provides a quick review of the Get, Change and Process design patterns, as you implement the business logic layer using the BOD command framework. - Implement the client library
The client library's primary purpose is to simplify and eliminate code on the client. The client library is essentially a Java layer to help Java applications integrate with the service architecture, with no additional code generation required. The client library already has support for session and authentication and provides Java-based clients a standardized mechanism to create the logical SDO objects to represent service requests. - Implement access control
Resources that Web services act upon are actually nouns which are represented by generated SDOs. The following is a brief overview of how access control policy works for BOD service modules. - Deploy and validating the TutorialStore service module with JUnit
After applying the WebSphere Commerce service module pattern, a BODTutorialStore-UnitTests project is created as a place to put JUnit tests for services created.