Tutorial: Creating a BOD service module

There are two sets of terminology used in this recipe project. One set of terms is used in the user interface while the other set is used in the database schema. Refer to the following table to understand the relationship between the two sets of terminology:

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 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 like boolean, or it can be a complex type, which is a construct 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. WebSphere 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" />

The service module that you create in this tutorial contains two nouns: Project and ProjectCollection. For this tutorial, these Project and ProjectCollection nouns are predefined for you. The following XSD files, which define the nouns, are provided within the RecipeServices.zip compressed file that you download for this tutorial:

• Project.xsd
• ProjectCollection.xsd

For this tutorial, the definitions of the two nouns 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 show in the summary view, and data included in the Details profile show in the details view.

• 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, which is 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

  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 WebSphere Commerce. The following diagram shows the schema definition for the Project noun:
  
  The following diagrams show the structure for Project noun:
  
  
  
  
  
  
  
  
  
  
• ProjectCollection noun:

  Data	Description	Applicable Access Profiles
  ProjectCollectionIdentifier	The ProjectCollection identification information.	Details
  Description	The ProjectCollection description.	Details

  The following diagrams show the structure for the ProjectCollection noun:
  
  
  
  

To manage the Project and ProjectCollection noun information that you create in this tutorial, you implement Get, Change, and Process services for the new service module:

• Get services You can use the Get service to retrieve Project and ProjectCollection 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')]]

  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

• Change services 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 is shown in the following examples:

  Update a project description:

  <oa:ActionExpression actionCode="Update" expressionLanguage="_wcf:XPath">/Project[1]/Description[1] </oa:ActionExpression>

  Add project material:

  <oa:ActionExpression actionCode="Add" expressionLanguage="_wcf:XPath">/Project[1]/Material[1] </oa:ActionExpression>

  Update project material:

  <oa:ActionExpression actionCode="Update" expressionLanguage="_wcf:XPath">/Project[1]/Material[1] </oa:ActionExpression>

  Delete project material:

  <oa:ActionExpression actionCode="Delete" expressionLanguage="_wcf:XPath">/Project[1]/Material[1] </oa:ActionExpression>

• Process servicesThe 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>

After completing this tutorial, you should be familiar with the following concepts:

• The WebSphere Commerce BOD command framework
• Extension and customization tasks.
• Logical model definitions.
• The Java Emitter Template.
• Service Data Objects.
• Eclipse Modeling Framework.
• The Data Service Layer wizard.
• 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.
• Generate Service Data Objects and object-relational metadata.
• Add language-specific exception messages to the properties files.
• Import mediators.
• Configure the data service layer for the Project service module.

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:

• RecipeServices.zip