| Architect: SOA
Jumpstart for Oracle Service Bus Development
by Ronald van Luttikhuizen and Eric Elzinga
Tutorial 1: First Spin
Getting to know Oracle Service Bus by exposing a simple service
Published October 2009
In this article:
The multinational Foo Inc. wants to reuse a service from its local Dutch subsidiary that exposes and retrieves customer information. The Dutch payload has to be transformed into Foo Inc.'s canonical data model that is in English.
In this tutorial we will develop an OSB project that invokes the KlantWebService; "klant" means customer in Dutch. The returned payload will be transformed into the English canonical data model using Assign and Replace activities. Deployment of the KlantWebService is described in the Installation and Configuration Guide.
Getting to know OSB basics such as Business and Proxy Services and basic routing rules and transformation capabilities that are based on XQuery. Oracle ESB mainly uses XSLT for transformation. OSB supports XSLT next to XQuery. Getting to know Oracle Workshop as IDE. OESB development is done in JDeveloper.
Oracle Service Bus Project
Let's start by creating a new Oracle Service Bus project.
OSB uses the notion of Business Services to define access to enterprise services such as Web Services, JMS destinations, and EJB's. A Business Service is configured by specifying its interface, type of transport it uses, its security requirements, and other characteristics. We will create a new Business Service for the "KlantWebService" based on its deployed WSDL.
First we need to import the WSDL and associated XSD's in our OSB project.
The "Review Resources" dialog shows the resources that will be imported: "KlantWebSerice.wsdl" and two referenced XSD's. Click "Finish". The wizard will import the WSDL and XSD's.
Note that the XSD filenames are based on the URL's in the WSDL. These XSD filenames might include question marks that are not well understood by Oracle Workshop. We need to rename these XSD's if this is the case; otherwise you can skip this step.
We continue by creating the Business Service that is based on the imported resources.
You have now exposed the deployed Web Service as Business Service in the OSB project and made it available as endpoint to route to. Next step is to create a Proxy Service that exposes the OSB Service to service consumers.
Proxy Services are the interface that service consumers use to connect with managed back-end services. Proxy Services are definitions of intermediary Web Services that the Oracle Service Bus implements locally. Proxy Services are configured by defining its interface using a WSDL and the type of transport it uses. Message processing logic is specified in message flow definitions when defining a Proxy Service.
The resources archive contains the WSDL and XSD of the Proxy Service we will be creating in the next steps.
You have now created both the Business and Proxy Service. We continue by wiring these together and defining the transformation between the English canonical data model and the Dutch Web Service payload.
The implementation of a Proxy Service is specified by a Message Flow definition. A Message Flow defines the flow of request and response messages through the Proxy Service. The following elements are used to construct a Message Flow: pipeline pair (sequence of stages for request and response flows), branch node (branching based on message content or operation), route node (definition of message destinations such as Business Services), and start nodes. Message Flow elements can be combined in arbitrary ways to form a tree structure with the start node always (and only) occurring as the root of the tree and the route nodes. The last nodes in a branch (leaf nodes) may be Route nodes or Echo nodes.
We need to transform the input from the Proxy Service to the input of the Business Service and vice versa for the response. We're going to add activities to the Message Flow of the newly created Proxy Service to achieve this.
The "KlantWebService" Business Service has 3 operations: "getAllKlanten", "getKlantById", and "addKlant". The "CustomerPS" Proxy Service has three matching operations: "GetAllCustomers", "GetCustomerById", and "AddCustomer". These will be routed to their Dutch equivalents using an Operational Branch.
Oracle Workshop now creates a branch for the "GetAllCustomers" operation and a "Default" branch that is chosen in case of any other operation.
We continue by defining the routing logic for each operation using Route Nodes and Routing activities. The transformation logic will be added afterwards. We'll leave the "Default" branch as is.
A Route Node performs request/response communication with another service. It represents the boundary between request and response processing for the Proxy Service. When the Route Node dispatches a request message, the request processing is considered complete. When the Route Node receives a response message, the response processing begins. The Route Node supports conditional routing as well as request and response transformations. Because a Route Node represents the boundary between request and response processing, it cannot have any descendants in the Message Flow.
After adding all routing activities the Message Flow looks like the following:
Figure 9: The final result of the Message Flow in which all operations are mapped
You have now defined the entire routing logic for the OSB project. We'll continue adding the required transformation logic using XQuery and OSB activities such as Assign and Replace. We need to transform the input of every Proxy Service operation to the input of the corresponding Business Service operation and vice versa for the output.
Oracle Workshop might warn the expression is invalid since the "cus" namespace prefix that is used in the expression cannot be resolved. If this is the case you need to declare the namespace prefix. Select the "Namespaces" tab and add a user namespace with "cus" as prefix and "http://www.waai.nl/CustomerService" as URI. Save and refresh the project.
We have now extracted the customer id from the incoming payload of the "GetCustomerById" operation and assigned it to the "customerId" variable. Next we need to construct the appropriate request payload for the "getKlantById" operation.
Expand the deployment and select Web Services ? KlantWebService. Select the "Testing" tab and use the WebLogic Test Client to view the payload of the operation. Execute the operation to view the response payload. Note that the KlantWebService is a dummy WebService and always returns the same customer details.
Figure 12: Testing the KlantWebService operations using the Test Client
Next step is to construct the request payload.
You have now replaced the entire node contents (indicated by ".") of the request body (indicated by "body") with the "getKlantById" request payload using the value of the "customerId" variable. This completes the Request Action flow!
We continue by completing the Response Action flow of the "GetCustomerById" operation using an XQuery transformation.
Figure 17: Final result of the XQuery mapping
Next step is to use the XQuery transformation to create the response content with it.
When all activities are added the Message Flow looks like the following:
Figure 20: Final result of the Message Flow
You have now completed the OSB project. It's time to take the project for a spin by deploying and testing it!
Deployment and Testing
Go to the server tab, right-click on the server connection, and select "Add and Remove Projects...". Add the "OSB Configuration" project and click "Finish" to deploy the OSB project. We will use Oracle Service Bus Console to test our project.
Oracle Service Bus Console enables you to control the service and policy configurations, and monitor system and operations tasks. Oracle Service Bus built-in test console is a browser-based test environment used to validate resources and inline XQuery expressions used in the Message Flow. It is an extension of the Oracle Service Bus Console. Using the test console, it is possible to configure the test object (Proxy Service, Business Service, XQuery, XSLT, MFL resource), execute the test, and view test results. It allows message flow tracing when testing a service, to examine the state of the message at specific trace points.
Log into Oracle Service Bus Console to view and test the OSB project. Click "Project Explorer", select the "WAAI_Case1_Customer_Service" project, and browse to the Customer Proxy Service you want to test. Click the "Launch Test Console" icon in the Actions dialog and test all operations of the Proxy Service.
Figure 21: Testing the Customer Proxy Service using Oracle Service Bus Console
The Testing Console shows the correct output of the Customer Proxy Service's operations. You can view the outcome of all individual steps in the "Invocation Trace" window.
You have completed the first tutorial in which you have developed an OSB project in Oracle Workshop that reuses a local Dutch service and exposes it using the English canonical data model. You should now have an understanding of OSB basic building blocks such as Business and Proxy Services, routing rules and transformation capabilities based on XQuery.