| Oracle® Enterprise Service Bus Quick Start Guide 10g (10.1.3.1.0) Part Number B28212-01 |
|
|
View PDF |
| Oracle® Enterprise Service Bus Quick Start Guide 10g (10.1.3.1.0) Part Number B28212-01 |
|
|
View PDF |
This chapter provides step-by-step instructions on creating and running the CustomerData tutorial.
This chapter includes the following topics:
In most business environments, customer data resides in disparate sources, including business partners, legacy applications, enterprise applications, databases, and custom applications. The challenge of integrating this data can be met using Oracle Enterprise Service Bus to deliver appropriate real-time data access to all applications that update or have a common interest in the same data.
For example, Oracle Enterprise Service Bus might accept data contained in a text file, transform it to a format appropriate for updating a database that serves as a customer repository, and route and deliver the data to that database.
To accomplish all the required tasks, Oracle Enterprise Service Bus follows the following basic steps, which are shown in Figure 5-1. These steps are simplified for the purposes of the introductory example. Additional information is provided in the step-by-step portions of this guide.
Figure 5-1 illustrates a scenario in which Oracle Enterprise Service Bus:
Receives the customer data from a file system as a text file, through an inbound file adapter service named CustIn. The CustIn adapter service sends the message to a routing service named CustIn_RS.
The CustIn_RS routing service transforms the data format from the file adapter's schema into the canonical XML schema, and sends the message to the routing service named CustOut_RS.
The CustOut_RS routing service:
Routes the message in the canonical format to the CRMOut file adapter service.
Applies a filter to the XML message payload to determine whether the message should be routed to the outbound adapter service for the Customer Information Database, CustDBOut.
Invokes the appropriate adapter services (as determined by the filter expression). Routing rules specify that messages bound for the CustDBOut service be sent synchronously, while those bound for the CRMOut service be sent asynchronously.
If the receiving adapter service is CustDBOut, then the CustDBOut service is invoked immediately and control is not returned to the CustOut_RS service until the message has been received by CustDBOut.
If the receiving adapter service is CRMOut, then the message is sent to JMS and control is immediately returned to the CustOut_RS service.
The outbound adapter service delivers the message to its associated external application.
This section provides the steps for loading, building, and registering components required for the tutorial scenario, as described in the following topics. These topics should be read and followed in the order in which they are presented.
"Registering Services with Oracle Enterprise Service Bus and Viewing in the ESB Control Console"
"Adding an Expression Filter to the CustOut_RS Routing Service"
Download the CustomerSample.zip file and unzip to the folder C:\Customer.
Figure 5-2 illustrates the directory structure used by the CustomerData tutorial.
The Customer folder contains following folders and files:
In folder
Schema folder: The Schema folder consists of following three XSD files:
CommonCustomer.xsd
CustomerDB.xsd
LegacyCustomer.xsd
create_customer.sql file
LegacyCustomer.xml file
LegacyCustomerCanada.xml file
query_customer.sql file
Figure 5-2 CustomerData Tutorial Directory Structure
You create adapter services using Oracle JDeveloper. To begin work in Oracle JDeveloper, you set up the folders that will hold the files related to your application. From the Applications Navigator, you create a folder for your application and a project within that application folder to hold the ESB tutorial files.
To create an application and a project for the tutorial, follow these steps:
Open Oracle JDeveloper as described in "Opening Oracle JDeveloper".
In the upper left panel, click the Applications Navigator tab.
Right-click Applications, then select New Application. The Create Application dialog box is displayed, as shown in Figure 5-3.
Figure 5-3 The Create Application Dialog Box
In the Application Name field, enter ESBSamples, and then click OK. The Create Project dialog box is displayed.
Click Cancel.
In the Applications Navigator pane, right-click ESBSamples, then select New Project. The New Gallery dialog box is displayed.
From the Categories navigator, select General and then Projects.
From the Items list, select ESB Project as shown in Figure 5-4.
Click OK. The Create ESB Project dialog box is displayed, as shown in Figure 5-5.
Figure 5-5 The Create ESB Project Dialog Box
In the Project Name field, enter CustomerData, and then click OK.
Oracle JDeveloper is displayed, as shown in Figure 5-6. The Applications Navigator is updated with the new application and project and the Design Tab contains, a blank palette.
Figure 5-6 Oracle JDeveloper – Application and ESB Project Added
The .xsd files that define the structure of the various message formats that will be integrated using Oracle Enterprise Service Bus in this tutorial are included when you install Oracle Enterprise Service Bus. To use them with the ESBSamples application, you must import them, as follows:
In the Applications Navigator pane, select CustomerData.
From the File menu, click Import. The Import dialog box is displayed, as shown in Figure 5-7.
From the Select What You Want to Import list, select Web Source, and then click OK. The Web Source dialog box is displayed, as shown in Figure 5-8.
To the right of the Copy From field, click Browse. The Choose Directory dialog box is displayed.
Navigate to the following directory, and then click Select.
C:\Customer\Schemas
The Web Source dialog box with the directory selected is displayed, as shown in Figure 5-9.
Click OK.
In the Applications Navigator pane, expand CustomerData and then WebContent.
The Applications Navigator should appear as shown in Figure 5-10.
Figure 5-10 Applications Navigator – ESBSamples/CustomerData/Web Content
To create adapter services, you must first create the Oracle Enterprise Service Bus system that will contain them, as described in the following list:
Note:
Before you create the Oracle Enterprise Service Bus system, you need to delete the existing CustomerData system.To do that, you need to open the ESB Control Console, click the CustomerData system, and click the Delete button. A Delete System dialog box is displayed, click Yes.
In Oracle JDeveloper, click Create System/Group icon shown in Figure 5-11.
The Create ESB System or Service Group dialog box is displayed, as shown in Figure 5-12.
Figure 5-12 The Create ESB System Or Service Group Dialog Box
Select System.
In the Name field, enter CustomerData.
Click OK.
Using Oracle JDeveloper, create an inbound file adapter service, named CustIn to read in text files. Follow these steps:
From the Components Palette, select Adapter Services.
Select File Adapter and drag it to the design area.
The Create File Adapter Service dialog box is displayed.
In the Name box, enter CustIn.
If CustomerData is not appearing in the System/Group box, then perform the following:
Click Browse.
Select ESB, Systems/Groups in project, CustomerData.
Click OK.
In the Adapter Service WSDL section, click the Configure Adapter Service Wsdl icon, shown in Figure 5-13.
Figure 5-13 Adapter Configuration Wizard Icon
The Adapter Configuration Wizard Welcome page is displayed.
In the Welcome page, click Next.
The Service Name page is displayed.
Click Next.
The Operation page is displayed.
In the Operation Type field, select Read File.
In the Operation Name field, replace Read with ReadCustomerData, as shown in Figure 5-14.
Click Next. The File Directories page is displayed.
In the Directory for Incoming Files (physical path) field, enter C:\Customer\In, and then click Next.
The File Filtering page is displayed.
In the Include Files with Name Pattern field, enter *.xml, and then click Next.
The File Polling page is displayed.
Change the Polling Frequency field value to 1 seconds, and then click Next.
The Messages page is displayed.
Click Browse.
The Type Chooser dialog box is displayed.
Expand the navigation tree to Type Explorer\Project Schema Files\LegacyCustomer.xsd and then select CustomerData, as shown in Figure 5-15, and then click OK.
The Adapter Configuration wizard appears as shown in Figure 5-16.
Figure 5-16 Adapter Configuration Wizard – Messages page
Click Next.
The Finish page is displayed.
Click Finish. The Create File Adapter Service dialog box is displayed with CustIn.wsdl appearing in the WSDL File field.
Click OK.
The CustIn_RS routing service is created along with the CustIn adapter service.
From the File menu, click Save.
Create an outbound database adapter service, named CustDBOut, to write messages to the Oracle Database Lite database, as follows:
Step 1 Begin the Adapter Configuration Wizard
Follow these steps to create an outbound database adapter service:
From the Components Palette, select Adapter Services.
Select Database Adapter and drag it to the design area. The Create Database Adapter Service dialog box is displayed.
In the Name field, enter CustDBOut.
If CustomerData is not appearing in the System/Group box, then perform the following:
Click Browse.
Select ESB, Systems/Groups in project, CustomerData.
Click OK.
In the Adapter Service WSDL section, click the Configure adapter service wsdl icon shown in Figure 5-13. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Click Next. The Service Connection page is displayed.
Click New. The Create Database Connection Welcome page is displayed.
Step 2 Begin the Create Database Connection Wizard
Follow these steps to create a database connection:
In the Create Database Connection Welcome page, click Next. The Create Database Connection Type page is displayed.
Enter Olite in the Connection Name field and select Oracle Lite from the Connection Type list, as shown in Figure 5-17.
Figure 5-17 The Create Database Connection Type Page
Click Next. The Create Database Connection Authentication page is displayed.
Specify field values as described in the following list, and click Next.
Username: System
Password: any
The Create Database Connection page is displayed, as shown in Figure 5-18.
Figure 5-18 The Create Database Connection Authentication Page
Click Next. The Create Database Connection page is displayed, as shown in Figure 5-19.
Figure 5-19 The Create Database Connection Page
Select Type 4 Driver from the Driver list, and click the Browse button next to the Library field. A Select Library dialog box is displayed, as shown in Figure 5-20.
Figure 5-20 The Select Library Dialog Box
Click New. The Create Library dialog box is displayed, as shown in Figure 5-21.
Figure 5-21 The Create Library Dialog Box
Click the Add Entry button. The Select Path Entry dialog box is displayed, as shown in Figure 5-22.
Figure 5-22 The Select Path Entry Dialog Box
Navigate to the Oracle_Home/integration/esb/lib/olite40.jar directory, as shown in Figure 5-22., where Oracle_Home is the directory specification for the Oracle home where you installed Oracle Enterprise Service Bus.
Click Select. The Select Path Entry dialog box closes and the Library Name field contains the value Olite40.jar in the Create Library dialog box, as shown in Figure 5-23.
Figure 5-23 The Create Library Dialog Box - Olite40.jar
Click OK. The Select Library dialog box is displayed with Olite40.jar in the Library Name field, as shown in Figure 5-24.
Figure 5-24 The Select Library Dialog Box - Olite40.jar
Click OK. The Create Database Connection page is displayed with the Library field populated with Olite40.jar, as shown in Figure 5-25.
Figure 5-25 The Create Database Connection Page
Enter the hostname, port, and SID details, as mentioned in the following list:
Host Name: localhost
JDBC Port: 1531
SID: OraESB
The Create Database Connection page is displayed, as shown in Figure 5-26.
Figure 5-26 The Create Database Connection Page
Click Next. The Create Database Connection Test page is displayed.
Click Test Connection. The Status field contains the string: Success!, as shown in Figure 5-27.
Figure 5-27 The Create Database Connection Test Page
Click Finish. The Service Connection page is displayed, as shown in Figure 5-28, where the Connection field contains Olite and JNDI Name contains eis/DB/Olite.
You have successfully created a new database connection called Olite, which is required to configure the database adapter.
Step 3 Complete the Adapter Configuration Wizard
Follow these steps to complete creating the outbound database adapter service:
Note:
Once you have created a database connection, the Adapter Configuration wizard continues, which enables you to create the outbound database adapter service.In the Service Connection page, as shown in Figure 5-28, click Next.
The Operation Type page is displayed.
In the Operation Type page, follow these steps:
Select Perform an Operation on a Table.
Deselect Insert Only, Update Only, Delete, and Select as shown in Figure 5-29.
Figure 5-29 Adapter Configuration Wizard – Operation Type
Click Next.
The Select Table page is displayed.
In the Select Table page, follow these steps:
Click Import Tables.
The Import Tables dialog box is displayed.
Select Auto-Query.
The Import Tables dialog box refreshes and appears as shown in Figure 5-30.
In the Available box, select CUSTOMER_ DATA and then click the right arrow button.
The CUSTOMER_DATA is added to the Selected box.
Click OK. The Select Table page is displayed, as shown in Figure 5-31.
Figure 5-31 Select Table – SYSTEM.CUSTOMER_DATA
Click Next.
The Define Primary Keys page is displayed.
In the Define Primary Keys page, select CUSTOMERID, and then click Next.
The Relationships page is displayed.
Click Finish. The Create Database Adapter Service dialog box is displayed with CustDBOut.wsdl appearing in the WSDL File field.
Click OK. You have successfully created the outbound adapter service named CustDBOut.
From the File menu, click Save.
Create an outbound JMS adapter service, named CRMOut, to write messages to the Customer Relationship Management application, as follows:
From the Components Palette, select Adapter Services.
Select JMS Adapter and drag it to the design area.
The Create JMS Adapter Service dialog box is displayed.
In the Name box, enter CRMOut.
If CustomerData is not appearing in the System/Group box, then perform the following:
Click Browse.
Select ESB, Systems/Groups in project, CustomerData.
Click OK.
In the Adapter Service WSDL section, click the Configure Adapter Service Wsdl icon.
The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Adapter Configuration Wizard Service Name page is displayed.
Click Next. The JMS Provider page is displayed.
Select Oracle Enterprise Messaging Service (OEMS) and then select Memory/File as shown in Figure 5-32.
Click Next in the JMS Provider page.
The Service Connection page is displayed.
Select LocalApplicationServer from the Connections list, and click Next.
The Operation page is displayed.
In the Operation Type field, select Produce Message, and then click Next.
The Produce Operation Parameters page is displayed.
Click the Browse button next to the Destination Name field.
The Select Destination dialog box is displayed.
Select All Types, jms, demoTopic(topic), as shown in Figure 5-33, and click OK.
Figure 5-33 Select Destination dialog box
The Produce Operation Parameters page is displayed with all the fields populated, as shown in Figure 5-34.
Figure 5-34 The Produce Operation Parameters Page
Click Next.
The Messages page is displayed.
In the Messages page, follow these steps:
Click Browse.
The Type Chooser dialog box is displayed.
In the Type Chooser dialog box, expand the navigation tree to Type Explorer/Project Schema Files/CommonCustomer.xsd, and click Customer, as shown in Figure 5-35.
Figure 5-35 Type Chooser – CommonCustomer.xsd
Click OK.
The Messages page appears with the Schema Location field populated with the location of the schema file, as shown in Figure 5-36.
Figure 5-36 Adapter Configuration Wizard – Messages Page CRMOut Adapter Service
Click Next.
The Finish page is displayed.
Click Finish. The Create JMS Adapter Service dialog box is displayed with CRMOut.wsdl file appearing in the WSDL File field.
Click OK. You have successfully created the outbound service named CRMOut.
From the File menu, click Save.
The outbound routing service, CustOut_RS specifies the route messages will take to arrive at their target destinations.
To create the CustOut_RS routing service, follow these steps using the Oracle JDeveloper:
From the Component Palette in the upper right section of Oracle JDeveloper, select ESB Services.
Drag the Routing Service from the Components Palette to the design view.
The Create Routing Service dialog box is displayed.
In the Name field, enter CustOut_RS.
If CustomerData is not appearing in the System/Group box, then perform the following:
Click Browse.
Select ESB, Systems/Groups in project, CustomerData.
Click OK.
Select Generate WSDL From Schemas.
Click Browse.
The Type Chooser dialog box is displayed.
In the Type Chooser navigator, expand Type Explorer, Project Schema Files, CommonCustomer.xsd, and then select Customer.
Click OK. The Create Routing Service dialog box is displayed with the Schema Location field populated with the URL for the schema file.
In the Operation Name box, enter MapCustomerData. The Create Routing Service dialog box is displayed, as shown in Figure 5-37.
Figure 5-37 Create Routing Service Dialog Box
Click OK. The CustOut_RS routing service is created, as shown in Figure 5-38.
Figure 5-38 The Oracle JDeveloper 10g - CustOut_RS Created
Follow these steps to specify the path that messages take from the CustIn_RS routing service to the CustOut_RS routing service:
Double-click CustIn_RS.
Click the plus (+) button to the left of Routing Rules. The Routing Rules panel is displayed.
Click the plus (+) button at the extreme right-hand side of ReadCustomerData.
The Browse Target Service Operation dialog box is displayed.
Select ESB, Services in project, CustomerData, CustOut_RS, MapCustomerData.
Click OK.
The Routing Rules panel is displayed, as shown in Figure 5-39.
Figure 5-39 The Routing Rules Panel - MapCustomerData Added
Click the icon next to the <<Transformation Map>> box.
The Request Transformation Map dialog box is displayed, as shown in Figure 5-40.
Select Create New Mapper File and click OK.
A CustomerData_To_Customer.xsl tab is added to the Oracle JDeveloper console, as shown in Figure 5-41. This tab enables you to graphically create a document transformation file to convert the structure of the file data to a canonical data structure.
Figure 5-41 CustomerData_To_Customer.xsl Tab – Initially
Drag and drop the imp1:CustomerData source element to inp1:Customer target element.
The Auto Map Preferences dialog box is displayed.
From the During Auto Map options, deselect Match Elements Considering their Ancestor Names.
The Auto Map Preferences dialog box is shown in Figure 5-42.
Figure 5-42 Auto Map Preferences Dialog Box
Click OK.
The CustomerData_To_Customer.xsl tab appears as shown in Figure 5-43.
As you can see, multiple links are created automatically. If you had not deselected the Match Elements Considering their Ancestor Names option, you would have to drag and drop each of the source elements to the target elements, one-by-one.
Figure 5-43 CustomerData_To_Customer.xsl Tab – Auto Mapped Connections
Expand the inp1:Customer/Profile target element.
Drag and drop the imp1:CustomerData/CampaignRating source element to the inp1:Customer/Profile/ActivityRating target element.
The CustomerData_To_Customer.xsl tab appears as shown in Figure 5-44.
Figure 5-44 CustomerData_CustIn_RS.xsl Tab – All Connections
From the File menu, click Save.
Follow these steps to specify the path that messages take from the CustOut_RS routing service to the CustDBOut adapter service:
Click the CustomerData.esb tab on the Oracle JDeveloper window.
Double-click CustOut_RS. The Routing Service panel is displayed.
Click the Plus (+) button to the left of Routing Rules. The Routing Rules panel is displayed.
Click the Plus(+) button at the extreme right-hand side of MapCustomerData.
The Browse Target Service Operation dialog box is displayed.
In the ESB Services navigator, expand ESB/Services in project/CustomerData/CustDBOut/write.
Click OK. The Routing Rules panel appears as shown in Figure 5-45.
Click the icon next to the <<Transformation Map>> box. The Request Transformation Map dialog box is displayed as shown in Figure 5-40.
Select Create New Mapper File, and click OK.
A Customer_To_CustomerDataCollection.xsl tab is added to Oracle JDeveloper, as shown in Figure 5-46.
Figure 5-46 Customer_To_CustomerDataCollection.xsl Tab – Initially
Drag and drop the inp1:Customer source element to the CustomerData target element.
The Auto Map Preferences dialog box is displayed.
From the During Auto Map options, ensure the Match Elements Considering their Ancestor Names is deselected.
The Auto Map Preferences dialog box should appear as shown in Figure 5-42.
Click OK. The Customer_To_CustomerDataCollection.xsl tab appears as shown in Figure 5-47.
Figure 5-47 Customer_To_CustomerDataCollectionTab – All Connections
You can expand the CustomerData target element to view the auto mappings.
From the File menu, click Save.
Follow these steps to specify the path that messages take from the CustOut_RS routing service to the CRMOut adapter service:
Click the CustomerData.esb in the Oracle JDeveloper window.
Double-click CustOut_RS routing service.
Click the Plus (+) button to the left of Routing Rules. The Routing Rules panel is displayed.
Click the Plus (+) button at the extreme right-hand side in the Rules region.
The Browse Target Service Operation dialog box is displayed.
Expand ESB/Services in Project/CustomerData/CRMOut, select Produce_Message, as shown in Figure 5-48.
Figure 5-48 Browse Target Service Operation - Produce Message
Click OK. The Routing Rules panel is displayed.
In the Applications Navigator, select Applications/ESBSamples/CustomerData/Resources and then double-click CustomerData.esb.
The CustomerData.esb Design tab now appears as shown in Figure 5-49.
Figure 5-49 The CustomerData.esb Design Tab
From the File menu, click Save.
Before you can view the services you have created with Oracle JDeveloper ESB Designer in the Oracle Enterprise Service Bus Control Console, you must register them with Oracle Enterprise Service Bus Server.
In the Applications navigator, right-click CustomerData, choose Register with ESB, and then click LocalIntegrationServer.
A message displays to indicate that the following services were successfully registered as shown in Figure 5-50:
CustomerData created
CustomerData.CRMOut created
CustomerData.CustDBOut created
CustomerData.CustOut_RS created
CustomerData.CustIn_RS created
CustomerData.CustIn created
Click OK.
View the Oracle Enterprise Service Bus configuration in the Oracle Enterprise Service Bus Control Console, as follows:
If the Oracle Enterprise Service Bus Control Console is currently open:
Click the refresh button and then click CustOut_RS.
If the Oracle Enterprise Service Bus Control Console is not open:
Select Start, All Programs, Oracle - Oracle_Home, Oracle ESB, ESB Control, to open the Oracle Enterprise Service Bus Control Console.
The Diagram tab is displayed, as shown in Figure 5-51.
Figure 5-51 ESB Control Console – After Oracle JDeveloper Configuration
The following steps describe how to add a filter to the CustOut_RS routing service so that only messages for customers with an address in the United States are sent to the CustDBOut adapter service for updating the customer database. First you need to determine the namespace for the service, then you use that namespace when specifying the filter expression, as follows:
Using the Oracle JDeveloper, follow these steps:
Click the CustomerData.esb tab in the Oracle JDeveloper window.
Double-click CustOut_RS.
Click the filter icon.
The Expression Builder is displayed.
In the WSDL Message box, expand Customer_request, Customer, inp1:Customer, Address and then select Country.
Click Insert Into Expression.
Specify the country as "US" as follows:
/inp1:Customer/Address/Country='US'
Click OK.
From the File menu, click Save.
Register the CustomerData service as shown in section "Registering Services with Oracle Enterprise Service Bus and Viewing in the ESB Control Console".
A message is displayed to indicate that the following services were successfully registered:
CustomerData.CustOut_RS updated
Refresh the view in the Oracle Enterprise Service Bus Control Console.
Select the CustOut_RS service.
Click the Diagram tab.
A filter icon appears next to the line representing the link between the CustOut_RS routing service and the CustDBOut adapter service, as shown in Figure 5-52.
Figure 5-52 Oracle Enterprise Service Bus Control Console – CustOut_RS Filter
Note:
For instruction on running the tutorial, refer to "Step-By-Step Instructions for Running the Tutorial".A series of demonstrations, activity and conceptual reference materials, and tutorials are also provided to increase conceptual knowledge and hands-on experience with Oracle Enterprise Service Bus. These materials are installed with Oracle Enterprise Service Bus in the Oracle_Home\integration\esb\samples directory.
In addition, you can find updated information about Oracle Enterprise Service Bus at following location:
http://www.oracle.com/appserver/esb.html
