Tutorial: Creating the Project BOD service module
In this tutorial, we will develop a new service module - Project. The services provided by the module will be Get, Change and Process. As part of creating the service module, we will design the logical model (noun) and physical model (database schema) based on the business requirement.
The Project service module stores and retrieves data, and performs business logic for our new Recipe tool in the Management Center. A recipe is an object that describes how to use several products that the retailer sells. It is made up of a set of ingredients, tools, and the instructions that show how to use the ingredients and tools to make the product.
Service modules provide the business logic to support operations on a business object, or noun. The noun that you are going to define in this tutorial is called the Project noun. Although the tool that is created in this scenario is called the Recipe tool, "Project" is more general, and can be applied to other retail segments. While a recipe is a food preparation Project, you could have projects that apply to home renovation, or a recreational hobby.
There are two sets of terminology that are used in this recipe project, one set is used in the user interface, while the other set is from the database schema. Refer to the following table to understand the relationship between the two sets of terms:
| Term used in user interface | Term used in logical schema | Description |
|---|---|---|
| Recipe | Project | The primary object that represents the recipe. For example, making coffee. |
| Recipe description | ProjectDescription | The description for the recipe. |
| Ingredients | ProjectMaterial | The materials that are used to make the final product. For example, coffee beans, water, and sugar. |
| DescriptionOfIngredient | ProjectMaterialDesc | The description for the materials. |
| RecipeInstruction | ProjInstr | The steps to make the final product. For example, boil the water; grind the coffee bean. |
| RecipeInstructionDescription | ProjInstrDesc | The description for the steps. |
| RecipeCollection | ProjectCollection | The tags to categorize the recipes, for example, food and drink. |
| RecipeCollectionDescription | ProjectCollectionDesc | The description for the collection. |
| Usage association | Usage association | The tools to be used to make the final product. For example a pot, and a coffee muller. |
The service module contains two nouns: Project and ProjectCollection. For this tutorial, the definition of the two nouns contains the information listed in the following table. The table lists the access profiles that includes the information. Data included in the Summary profile will be shown in the summary view, and data included in the Details profile will be shown in the details view.
For the Project noun:
| Data | Description | Applicable access profiles |
|---|---|---|
| ProjectIdentifier | Project identification information | Summary, Details |
| Tool | The tools that are used in the project. All tools must come from existing catalog entries. | Details |
| TimeToComplete | The time, specified in minutes, that is required to complete the Project | Summary, Details |
| Difficulty | The degree of difficulty of the project: easy, normal, or difficult | Summary, Details |
| Material | The materials for the project. | Details |
| Instruction | The instructions to complete the project. | Details |
| Description | The Project noun description. | Summary, Details |
| Collection | The relationship between the Project noun and the ProjectCollection noun. A ProjectCollection can have multiple Projects. | Details |
For the ProjectCollection noun:
| Data | Description | Applicable Access Profiles |
|---|---|---|
| ProjectCollectionIdentifier | The ProjectCollection identification information. | Details |
| Description | The ProjectCollection description. | Details |
You can use the Get service to retrieve Project and ProjectCollection noun information 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')]]
- Find Projects by ProjectCollection UniqueID:
- /Project[ProjectCollection[ProjectCollectionIdentifier[(UniqueID='10001')]]]
- Find Projects by Materials related catentry UniqueID:
- /Project[Material[CatalogEntry[CatalogEntryIdentifier[(UniqueID='10001')]]]]
- Find Projects by Tools related catentry UniqueID:
- /Project[Tool[CatalogEntry[CatalogEntryIdentifier[(UniqueID='10001')]]]]
- Find Projects by search expression:
- /Project[search(contains(ProjectIdentifier/ExternalIdentifier/Name,'MyProjectName'))]
- Retrieve all ProjectCollections:
- /ProjectCollection
The Change service updates project information for a Project noun. The Change service can add, update or delete information. The Project noun is divided into the following distinct noun parts:
- Material
- Tool
- Instruction
- Description
- Collection
In this tutorial, you also implement a change service for each noun part. A subset of the change services are shown in the following examples:
- Update a Project's Description:
- <oa:ActionExpression actionCode="Update" expressionLanguage="_wcf:XPath">/Project[1]/Description[1] </oa:ActionExpression>
- Add a Project's Material:
- <oa:ActionExpression actionCode="Add" expressionLanguage="_wcf:XPath">/Project[1]/Material[1] </oa:ActionExpression>
- Update a Project's Material:
- <oa:ActionExpression actionCode="Update" expressionLanguage="_wcf:XPath">/Project[1]/Material[1] </oa:ActionExpression>
- Delete a Project's Material:
- <oa:ActionExpression actionCode="Delete" expressionLanguage="_wcf:XPath">/Project[1]/Material[1] </oa:ActionExpression>
The Process service creates and deletes the Project noun and Project Collection noun. In this tutorial, the following process actions are implemented:
- Create a project:
- <oa:ActionExpression actionCode="Create" expressionLanguage="_wcf:XPath">/Project[1]</oa:ActionExpression>
- Delete a project:
- <oa:ActionExpression actionCode="Delete" expressionLanguage="_wcf:XPath">/Project[1]</oa:ActionExpression>
- Create a project collection:
- <oa:ActionExpression actionCode="Create" expressionLanguage="_wcf:XPath">/ProjectCollection[1] </oa:ActionExpression>
- Delete a project collection:
- <oa:ActionExpression actionCode="Delete" expressionLanguage="_wcf:XPath">/ProjectCollection[1] </oa:ActionExpression>
Learning objectives
The learning objectives for the tutorial are:
- To gain an understanding of the WebSphere Commerce BOD command framework
- To get an overview of extension and customization tasks.
Time required
This tutorial takes approximately 4 hours to finish. If you explore other concepts related to this tutorial, it might 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.
- Install the Java Emitter Template (JET) package
- Set up the development environment for creating WebSphere Commerce services
- Downloaded and extracted the RecipeServices.zip file to a temporary location on the hard disk.
- Published the consumer direct sample store.
Prerequisites
To complete this tutorial, familiarize yourself with the following terms and concepts:
- Java programming language
- XPath
- XSD
- Web services
- XML
- WebSphere Commerce services
- WebSphere Commerce data service layer
- Nouns
- Relational databases
- SQL
Lessons in this tutorial
- Create an extended sites store for the Recipes tool customization
This lesson details how to create an extended sites store with a custom catalog for use in the Recipes tool tutorials. This extended sites store is used in other tutorials in the Recipes tool series of tutorials and must be created before proceeding any of the five tutorials in the series. - Define the Project noun
Any service that uses an XML schema requires a logical model definition. For WebSphere Commerce, the logical model is represented as nouns and noun parts. Nouns are the business objects in the application, while noun parts are parts of those objects that have been given distinct names so that they can be handled independently of the noun. - Define the database schema
In this step we will customize the physical layer by adding tables to contain recipe information in the WebSphere Commerce database schema. - Generate the Project service module projects
The Java Emitter Template (JET) is an Eclipse-enabled template engine for generating applications based on model-driven architecture transformations. By defining a simple XML file describing the module, the JET plug-in for Rational Application Developer (RAD) can generate the basic WebSphere Commerce service module code for you. Afterwards, you can complete the module by filling in the specific business logic, 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 Project noun
Once you have the base code and project structure generated using the Java Emitter Template (JET), you can generate the Service Data Objects (SDOs) that implement the logical data model of the Project and ProjectCollection nouns. SDOs are Java objects that represent the nouns in the logical model. You can use the Eclipse Modeling Framework (EMF) to generate these SDOs from the noun definitions. - 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 physical schema. - Add language specific exception messages
In this lesson, you add language-specific exception messages to the properties files used by the mediators and commands. You 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 Project service module
In this lesson we will configure the data service layer for the Project service module, using XML to provide the necessary mappings. - Implement the business logic layer
The business logic layer contains the commands used in this tutorial.To save time, you are importing these commands directly from the provided tutorial code.
- Implement the client library
The primary purpose of the client library 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 that are represented by generated SDOs. This lesson contains a brief overview of how access control policy works for BOD service modules. - Validate the Project service module with JUnit
After applying the WebSphere Commerce service module pattern, a Project-UnitTests project is created as a place to put JUnit tests for the services that you have created.