Working With Complex Data Types from a Process in WebSphere Integration Developer 6

Web Age Solutions Inc.

Introduction

In the previous tutorial Working With Simple Data Types from a Process in WebSphere Integration Developer 6 we learned how to work with simple input and ouput data types from a process. In real life, you may have to work with more complex data types such as Order, Address and Customer. In this tutorial, we will learn how to define complex data types and use them from a process. We will also learn how to define your own service interface and implement it from a process.

Prerequists

This tutorial builds on the previous tutorial WASKB020 - Working With Simple Data Types from a Process in WebSphere Integration Developer 6. You must complete that tutorial first.

The Business Logic

In this tutorial, we will build a price quote and availability process. The caller of the process will pass a price quote request object that has the following fields.

1. BusinessID - The unique identifier of the business requesting the price quote. Type: xsd:string.
2. ProductSKU - The Stock Keeping Unit number that uniquely identifies the product. Type: xsd:string.
3. Quantity - The amount of the product required. Type: xsd:double.

The process prepares a quote response message that has these fields.

1. QuoteID - An identifier for the quote. If an order is placed by the caller at a later time the quote number will be used to refer to the quote. Type: xsd:string.
2. StatusCode - Indicates the nature of the quote response. For example, "ITEM_AVAILABLE" indicates that sufficient quantity of the product is available in the inventory. "ITEM_UNAVAILABLE" indicates otherwise. "ITEM_UNKNOWN" indicates an invalid product SKU. Type: xsd:string.
3. ProductSKU - The product identifier. Type: xsd:string.
4. UnitPrice - The unit price for the product. Type: xsd:double.
5. Currency. Type: xsd:string.

Define the Data Types

In WID, custom data types are called Business Objects. They are defined as XML elements in schema files. The tool simplifies developing the XML schema. You don't really have to know much about XML schema to complete this tutorial or get useful work done out of WID. At the same time, it is recommended that you learn XML schema before getting into more advanced SOA based application development.

Launch WID if it is not already running. Start the WebSphere Process Server.

The Business Integration module - SimpleModule - should have been already created from the previous tutorials. Expand it. Right click on Data Types and select New->Business Object.

Enter the following values.

Module: SimpleModule
Namespace: Accept the default. For more serious programming, there will be a corporate standard for the namespace. Namespace is important. Keep in mind that the fully qualified name of the data type is actually a combination of the namespace and the type name.
Folder: types. It is a good idea to define your types in a sub folder rather than directly in the root folder of the module.
Name: QuoteRequest. This is the type name.

Click on Finish.

System opens the data type in the business object editor. Wait for the workspace to be re-built and re-published. This can take up to a minute.

Activate the Properties view. Select the QuoteRequest type in the editor. You should see various properties of the type in the Properties view.

Now, we will add various attributes to the business object. Right click on the QuoteRequest business object and select Add Attribute. With the newly added attribute selected, go to the Properties view. Make sure that the Description tab is selected. Enter the following values.

Name: BusinessID
Type: string

Add two more attributes as follows.

Name: ProdctSKU
Type: string

Name: Quantity
Type: double

At this point the business object will look like this.

Save changes (Control+S). System will build the workspace and publish the project. Wait for this to be over.

Create another business object called QuoteResponse. Add the following attributes.

Name: QuoteID
Type: string

Name: StatusCode
Type: string

Name: ProductSKU
Type: string

Name: UnitPrice
Type: double

Name: Currency
Type: string

Save Changes. Wait for publishing to complete.

Refine the Data Type

The StatusCode attribute of the QuoteResponse object should contain a limited set of values. We can enforce that by refining the data type a little more. In the business object editor, select the StatusCode attribute. In the Properties view, select the Only permit certain values check box. Select the Enumeration radio button. Add the following values.

1. ITEM_AVAILABLE
2. ITEM_UNAVAILABLE
3. ITEM_UNKNOWN

Save changes. Close all business object editors.

Define an Interface

In the previous tutorials, we chose to have the interface generated by the system. In this step, we will define an interface that the price quote business process will later implement.

In the Business Integration view, right click on Interfaces and select New->Interface. Enter the following values.

Module: SimpleModule
Namespace: Accept the default.
Folder: interfaces
Name: IPriceAvailabilityQuote

Click on Finish. System will open the interface in the editor. An interface is nothing other than an abstract service description in a WSDL file. If you know WSDL syntax, an abstract service is defined using the <portType> element. The interface editor is quite easy to use and you don't need to know much about WSDL file syntax.

Our process will accept a QuoteRequest object and reply a QuoteResponse object. As a result, we need to add a request-response type operation to the interface.

In the interface editor, click on the Add Request Response Operation toolbar button. Set the name of the operation to getPriceAvailabilityQuote.

Right click on the getPriceAvailabilityQuote operation and select Add Input. Change the name of the input to request. By default, the data type of the input is string. Click on string and select QuoteRequest.

Right click on the getPriceAvailabilityQuote operation again and select Add Output. Set the name of the output to response. Change the data type to QuoteResponse.

Save changes. System will create the interface in the IQuoteRequest.wsdl file within the interfaces folder. The interface definition is now complete.

Create the Process

In this step we will create a price quote request process that implements the IQuoteRequest interface.

Expand SimpleModule->Business Logic->Processes. Right click on Processes and select New->Business Process. Next to the Folder text box, use the Browse button to select the procs folder that was created in a previous tutorial. Enter PriceAvailabilityQuote as the name of the process. Click on Next. Choose Select and existing interface. Click on the Browse button and select the IPriceAvailabilityQuote interface. Click on OK. There is only one operation in that interface (getPriceAvailavilityQuote) and system should select it by default.

Click on Finish.

Investigate the Generated Process

A newly created process has useful amount of work already done. For example, note the following.

1. A variable called Request of type QuoteRequest is already added. This variable is also configured with the Receive activity to store the input data.
2. A variable called Response of type QuoteResponse is already added. This variable is also configured with the Reply activity so that the reply data is obtained from this variable.

This, obviously saves us a lot of time.

Work With the Input Data

We will first learn to work with the input data. When a process begins to execute, system automatically creates a new object to store the input data and initializes the process variable associated with the receive activity. In other words, we don't have to do anything to initialize our Request variable. System takes care of this.

Add a snippet activity below the receive activity. Change the name of the snippet activity to PrintRequest. Set the Java code for the snippet to as follows.

System.out.println("Received a quote request"); 
System.out.println("Business ID: " + Request.getString("BusinessID")); 
System.out.println("Product: " + Request.getString("ProductSKU")); 
System.out.println("Quantity: " + Request.getDouble("Quantity"));

Save changes. What went on here? Every process variable is actually a Java object of class commonj.sdo.DataObject. The class provides a simple getter methods (such as getString and getDouble) to retrieve the fields of the business object. You just have to be careful so that the attribute names are spelled correctly.

Add the Process to Assembly

We must add the process to the module assembly before we can test it. Double click on SimpleModule->SimpleModule to open the assembly editor. Drag and drop the PriceAvailabilityQuote process into the assembly editor. Save changes.

Test the Process

If the system is publishing the project, wait for it to complete. In the Servers view, right click on the server and select Restart Project->SimpleModuleApp.

In the assembly editor, click anywhere and select Test Module. In the automated test client, choose these values.

Component: PriceAvailabilityQuote
Interface: IPriceAvailabilityQuote
Operation: getPriceAvailabilityQuote

Enter some values for the request fields as shown above. Then click on Continue. Make sure that the Console view shows the correct output.

Close the test client. Don't save changes.

Work With Output Data

It is somewhat more difficult to work with the output data. This is because, system does not automatically instantiate an object and initialize the output variable. We will need to write code to do that.

First, we should import certain Java packages. This will simplify coding later. Open the PriceAvailabilityQuote business process in the editor. In the editor, click anywhere in the white canvas area. This will deselect any activity and the Properties view will show the property of the process. Click on the Java Imports tab in the Properties view. Add these import statements.

import com.ibm.websphere.bo.BOFactory; 
import com.ibm.websphere.sca.ServiceManager; 

Add a new snippet activity below the PrintRequest snippet activity. Change its name to PrepareResponse.

As the Java code for thie newly created snippet, enter the following.

BOFactory bofactory = 
    (BOFactory) ServiceManager.INSTANCE.locateService("com/ibm/websphere/bo/BOFactory"); 
Response = bofactory.create("http://SimpleModule/types", "QuoteResponse"); 
     
Response.setString("QuoteID", "123456"); 
Response.setString("ProductSKU", Request.getString("ProductSKU")); 
Response.setString("StatusCode", "ITEM_AVAILABLE"); 
Response.setDouble("UnitPrice", 100.00); 
Response.setString("Currency", "USD"); 

Save changes.

The crucial line from the code above is:

Response = bofactory.create("http://SimpleModule/types", "QuoteResponse"); 

This creates a new business object instance and initializes the Response process variable. The create method takes as argument the namespace and the type name.

Test the Process

Restart the SimpleModuleApp. If publishing fails, take the steps mentioned before.

Right click anywhere in the assembly editor and select Test Module. Choose the PriceAvailabilityQuote component as before. Enter some values for the request fields. Click on Continue.

Make sure that the response object shows correct values in various fields.

Solution

You can download the fully completed project as a project interchange format from this link.

Summary

In this tutorial, we learned how to:

1. Define your own complex data types. The business object editor lets us define XML schema elements without knowing anything about XML schema.
2. Define your own interface (or WSDL portType elements). Once again, the tool significantly simplifies the process.
3. Create a new BPEL process that implements the interface.
4. Read fields from the input data.
5. Create the output object and set various feilds.
6. Test a process by entering fields of complex data typed objects.

Feedback