Oracle Service Bus 11g Development Cookbook:

Name: Oracle Service Bus 11g Development Cookbook
Brand: Packt
SKU: 9781849684446
Availability: InStock

~~$39.99~~ $27.98

Book Jan 2012 522 pages 1st Edition

What do you get with eBook?

Instant access to your Digital eBook purchase

Download this book in EPUB and PDF formats

Access this title in our online reader with advanced features

DRM FREE - Read whenever, wherever and however you want

Buy Now

Product Details

Publication date : Jan 24, 2012

Length 522 pages

Edition : 1st Edition

Language : English

ISBN-13 : 9781849684446

Vendor :

Oracle

Category :

Programming

Languages :

Java (Beginner)

Concepts :

Application Development

Tools :

Oracle Database (Beginner)

View table of contents

Preview Book

Chapter 1. Creating a basic OSB service

In this chapter, we will cover the following topics:

Creating a new OSB project
Defining a folder structure for the OSB project
Importing an already existing project into Eclipse OEPE
Creating a business service to call an external SOAP-based web service
Generating a pass-through proxy service
Deploying the OSB configuration from Eclipse OEPE
Testing the proxy service through the OSB console
Testing the proxy service through soapUI
Creating a proxy service with a WSDL-based interface
Using a routing action to statically route to another service
Using an operational branch to implement multiple WSDL operations in a proxy service
Using an XQuery transformation to map between the different data models of the services

Introduction

In this chapter, we will cover some basic recipes to get the reader started working with the Oracle Service Bus (OSB). We will first develop the simplest possible service on the OSB with only one proxy service and then recipe by recipe add some more functionality to that service. In contrast to the other chapters, the recipes in this chapter are dependent on each other, and all the recipes of this chapter should therefore, be done in order. On the other hand, each single recipe can also be applied standalone by importing the 'getting-ready' project referenced in the Getting, Ready section of each recipe.

In some of the recipes, we will also define the best practices and development conventions that we will use for this book, however, they are also applicable in any other project. We teach how to best structure a project using Eclipse OEPE (with the OSB plugin installed).

In this recipe, we will implement a mediation service in the OSB, which consumes a web service from an external CRM system.

Creating a new OSB project

In order to develop on the Oracle Service Bus, an OSB project needs to be available. This recipe will show how such an empty OSB project can be created. Such a project can either be created through the web-based OSB console or through the more developer-friendly Eclipse OEPE. Eclipse OEPE is an Eclipse IDE with Oracle Enterprise Plugin for Eclipse (OEPE) and the OSB plugin installed.

Getting ready

Make sure that you have access to a working Eclipse OEPE.

How to do it...

In Eclipse OEPE, perform the following steps:

From the File menu, pick New | Other.
Type Oracle Service Bus in the Wizards tree list:
Choose Oracle Service Bus Project from the list and click on the Next button.
Enter basic-osb-service into the Project name fild:
Click on the New button to create an OSB Configuration (if there is not yet one).
Enter osb-cookbook-configuration into the Configuration name field.
Click on the Finish button to create the empty OSB project.
Click on Yes to confirm that Eclipse OEPE will switch to the Oracle Service Bus perspective.

We have now created an empty OSB project inside our Eclipse worksace.

How it works...

An OSB project created through Eclipse OEPE is just a folder created below the location of the workspace. Visually, Eclipse OEPE shows it wrapped inside the osb-cookbook-configuration OSB configuration, but they are really both on the same level, just a subfolder of the workspace folder.

The project contains a .project file and a .settings folder like any Eclipse project. These files hold the necessary meta information about the project. An OSB project has the special Oracle Service Bus facet assigned.

This empty project can now be used to create the different OSB artifacts necessary for an OSB service. They can either be placed directly inside the project folder or a subfolder structure can be created in order to organize the OSB project. How to create a folder structure will be shown in the next recipe, Defining a folder structure for the OSB project.

There's more...

A new OSB project can also be created through the OSB console. The main difference to the approach shown before is that, through the OSB console we directly work on a running Oracle Service Bus instance. When using Eclipse OEPE, the project is stored in the Eclipse workspace and needs to be later deployed to an OSB instance. See the next recipe, to learn how to create a folder structure for holding the different OSB artifacts.

Defining a folder structure for the OSB project

After creating the empty OSB project, we will prepare a folder structure to be used to organize the project. OSB allows you to use folders to build-up a project structure which helps to better find the various artifacts inside the OSB project.

Getting ready

Make sure that the empty OSB project—basic-osb-service from the previous recipe is available in the Eclipse OEPE. Also make sure that the Oracle Service Bus perspective is active in Eclipse. The active perspective can be identified in the upper-right corner of the Eclips window:

To switch to another perspective, click on the Window menu, select Open Perspective | Other and then select the Oracle Service Bus in the list of perspectives.

If after a while a certain perspective gets messed up and some windows or views are missing, then the perspective can always be reset to the factory settings by clicking on the menu Window | Reset Perspective and then confirming the dialog with the OK button.

How to do it...

In Eclipse OEPE, perform the following steps:

Right click on the basic-osb-service project and select New | Folder.
Enter proxy in the Folder name field:
Repeat these two steps for the folders business, wsdl, xsd, and transformation. These are the most common folders and they altogether form the basic OSB project structure used in this book.

How it works...

Folders help to structure the projects and by that organize the different artifacts that we will create later. The folder structure will also be visible after the deployment of a project in the OSB console. So at runtime, if someone (that is, the administrator) needs to navigate to a certain artifact through the console, a clever folder structure can make life much easier.

The meaning of the folder structure that we will use in this book is listed in the following table:

Folder name	Used for organizing
`business`	business services artifacts
`proxy`	proxy services artifacts
`wsdl`	SOAP-based web service interfaces
`xsd`	the XML schema files
`transformation`	Artifacts for doing data model transformations, such as XQuery and XSLT scripts

In some specific recipes, we will add some additional folders. The ones shown in this recipe just represent the most commonly used ones.

Importing an already existing project into Eclipse OEPE

Working with Eclipse OEPE, there is often a need to open an already existing OSB project, which is (no longer) in your Eclipse workspace. This recipe will show how to import an existing project. It should be used in all future recipes, when the Getting, ready section asks for importing an existing OSB project as the base for following the recipe.

Getting ready

Make sure that you have access to a working Eclipse OEPE.

How to do it...

In Eclipse OEPE, perform the following steps:

From the File menu select Import.
Type Existing in the Select an import source tree list.
Select Existing Projects into Workspace from the tree and click Next.
Click on the Browse button to specify the root directory from where to import the project.
Navigate to the \chapter-1\getting-ready folder and click on the OK button.
Select the already-existing-osb-project from the list of projects to import and select the Copy projects into workspace option:
Click on the Finish button.

The project is now imported in Eclipse OEPE but will be placed outside of the OSB Configuration and therefore, will have an error marker.

To move it into the OSB Configuration, just drag the imported already-existing-osb-project in the Project Explorer into the osb-cookbook-configuration project. Now the project is ready to be used.

How it works...

To import the OSB project into Eclipse OEPE, we just used the standard import functionality of Eclipse. In order for that to work, the project needs to have the .project, which is automatically created when using Eclipse OEPE to create an OSB project.

The project has to be moved into the OSB configuration in order to be able to work with it, that is, deploy it to the OSB server. Dragging the project into the OSB configuration is only reflected inside Eclipse, it does not change the location of the files on the disk.

Creating a business service to call an external SOAP-based web service

With the basic folder structure of the OSB project in place, we are ready to create our first OSB service. We will start with the business service Customer Service which will act as a wrapper of the external service. Business services in OSB are required definitions to exchange messages with enterprise information systems—such as databases and queues or other web services. The external service is a web service offered by a fictive CRM system. The business service will allow the definition of all sorts of properties for controlling how the external service is invoked:

Getting ready

Make sure that the external web service we want to invoke is started by running the script \chapter-1\getting-ready\misc\customer-external-webservice\start-service.cmd. This service is implemented using soapUI's capabilities for creating mock services.

Verify that the service is running and available by asking it for its WSDL definition. Enter the following URI in a browser window: http://localhost:8088/mockCustomerServiceSOAP?WSDL:

How to do it...

In Eclipse OEPE, perform the following steps:

In the project tree, right-click on the business folder and select New | Business Service.
Enter CustomerService into the File name field, check a second time that the business folder is selected, and click on the Finish button:
A new business service artifact is created in the business folder and the editor for the business service opens automatically.
Navigate to the General tab, if it does not already have the focus, and select the WSDL Web Service radio button.
Click on the Browse button and a pop up window will show up, where the WSDL resource of the external service to be wrapped, can be selected.
Click on the Consume button.
A second pop-up window will show up where the WSDL resource can be specified:
Select URI in the Service Resource drop-down listbox.
In the URI field, enter the URL of the WSDL resource to consume. The external service provides its WSDL through the following URL: http://localhost:8088/mockCustomerServiceSOAP?WSDL.
Click on the OK button and Eclipse will consume the WSDL from this URL.
Select the CustomerServiceSOAP port on the next window.
Click on the OK button.
Select Yes on the pop-up message window to confirm that the transport configuration settings will be overwritten by the information from the selected WSDL.
Save the OSB project by selecting File | Save.
In the Project Explorer, right-click on the imported WSDL file mockCustomerServiceSOAP.wsdl and select Rename. Enter CustomerService.wsdl into the New name field of the pop-up window and confirm.
In the Project Explorer, drag the CustomerService.wsdl file into the wsdl folder and drop it there. All the references to the WSDL file are automatically adapted by Eclipse OEPE.
Navigate to the Transport tab and check that the Endpoint URI has been replaced with the service endpoint setting from the WSDL that we consumed:
Save the artifact by selecting File | Save or by clicking on the Save toolbar button.

How it works...

The business service acts as a wrapper of our external service. Once created, we will no longer have to use the WSDL to refer to the external service, but can use the business service. This forms an additional abstraction layer, which will become handy later in some of the more advanced recipes to enable functionality in the OSB, which is applied before the real endpoint is invoked, such as SLA monitoring, service throttling, service pooling, and others. Sentence is too long, runs on too long. Would be better split into two sentences.

Generating a simple pass-through proxy service

After we have created the business service wrapping the external web service, we can now create the proxy service. The proxy service will allow a consumer to call our service on the OSB. If the OSB needs to support the same web service interface as the backend service does, then the quickest and easiest way is to create a pass-through service:

Getting ready

This recipe continues with the result of the previous recipe. If necessary, the basic-osb-service project at that stage can be imported from here: \chapter-1\getting-ready\business-service-created.

How to do it...

In Eclipse OEPE, perform the following steps:

In the project tree, right-click on the CustomerService.biz artifact and select Oracle Service Bus | Generate Proxy Service.
Enter CustomerService in the File name field and select the proxy folder for the location of the new proxy service.
Click on the Finish button.
Click on the Transport tab and check the value of the Endpoint URI field. It should be /basic-osb-service/proxy/CustomerService.
Navigate to the Message Flow tab and have a look at the message flow, which has been generated by Eclipse OEPE. A Route node with a nested Routing action has been created with its Invoking properties set to Use inbound operation for outbound:

How it works...

Applying this recipe created the simplest possible proxy service. The proxy service offers the same SOAP-based web service interface as the business service/external service, so it's basically just doing a pass-through of the request and response message.

This can be handy if we want to use the OSB for adding an additional abstraction layer to apply service virtualization. If all the service consumers no longer access the external services directly, but only through the OSB proxy-service, a lot of the features of OSB can be used transparently by a service consumer, such as SLA monitoring and alerting, service pooling and throttling, or message validation. This directly supports the main goal of service virtualization—adding operational agility.

By setting the Invoking property to Use inbound operation for outbound, we make sure that the whole WSDL with all its operations is handled by one single Routing action. The inbound operation name on the proxy service is used as the outbound operation name invoked on the business service. Apart from the Routing action there are no other actions in this proxy service. By that, both the request and the response messages in the $body variable are not touched by the OSB. This guarantees that the overhead of adding OSB as a service virtualization layer has minimal impact on the performance.

Deploying the OSB configuration from Eclipse OEPE

Before we can test an OSB service, we need to deploy it to a running OSB server. Such a server can either be locally on the same machine or it can be on another, remotely accessible server. In this recipe, we will only use the functionality provided by Eclipse OEPE to deploy our service, because it's the simplest of the possible options for deployment. Of course there exists other, more automatic and repeatable ways for deployment through WLST or Apache Ant, but in this book, the deployment through Eclipse OEPE as shown here is good enough.

Getting ready

Make sure that the OSB server is running locally on your machine. The easiest way to check that it's up and running is navigating to the OSB console in a browser window. Enter the URL http://[OSBServer]:[Port]/sbconsole (replacing [OSBServer] with the name of the server and [Port] with the port of your installation) and you should get the login window of the OSB console. Check if the OSB server is up and running, especially when running the OSB on a managed server.

Make sure that the Oracle Service Bus perspective is the active one in Eclipse OEPE. The perspective is visible in the top-right corner of the Eclipse window.

Make sure that the project with the result from the previous recipe is available in Eclipse OEPE. If not then it can be imported from here: \chapter-1\getting-ready\pass-through-proxy-service-created.

How to do it...

First we need to create the server reference inside Eclipse OEPE and after that we can deploy the OSB configuration with its projects to the server.

In Eclipse OEPE, perform the following steps to create a server:

Switch to the Servers tab and right-click in the empty window.
Select New | Server.
In the Define a New Server window, select the right WebLogic Server version (Oracle WebLogic Server 11gR1 PatchSet 3 in our case, this might vary).
Click on the Next button twice.
Select the Local option and select the Domain Directory of the local OSB server installation. If the Domain Directory drop-down list is empty, then click on Browse button to navigate to the domain directory on your machine:
Click on the Finish button.
Now the local OSB server is configured in Eclipse OEPE. The next step is to deploy the OSB configuration to this sever. Still in Eclipse OEPE, perform the following steps:
On the Servers tab, right-click on the server item that you just created and select Add and Remove.
In the Available list on the left, click on the osb-cookbook-configuration OSB configuration.
Click on Add to move it to the Configured list on the right and click on the Finish button.
The OSB configuration is deployed to the running OSB server and after a while the status will change from [Started] to [Started, Republish].
Right-click on the OSB server and select Publish.
After a while the status will change to [Started, Synchronized], indicating that Eclipse OEPE and the OSB server are synchronized.
Expand the tree and the status of each single OSB project withinthe OSB configuration is shown:

The OSB configuration is now successfully deployed and ready to be used.

How it works...

Behind the scenes, Eclipse OEPE is creating a JAR file (a Java Archive) with all the artifacts which belong to the OSB configuration and deploys that archive to the OSB server.

The mechanism to deploy directly from Eclipse should only be used during development. Later when deploying to integration, quality assurance, or a production system, of course, a more automatic and reproducible way is necessary. This can be achieved through Apache Ant and WLST.

There's more...

In this section, we will show the alternative ways for deploying a project to an OSB server.

Deploying to a remote server from Eclipse OEPE

Eclipse OEPE can also be used to deploy to a remote server. Just click on the Remote option when defining the WebLogic Server in the New Server wizard:

Creating an OSB Configuration Jar and use the OSB console to deploy it

An OSB configuration can also be deployed by using the OSB console. In Eclipse OEPE, perform the following steps:

In the Project Explorer, right-click on the OSB Configuration that you want to deploy to and select Export | Oracle Service Bus – Configuration Jar.
In the pop-up window, select the resources to export, enter the location of the configuration jar into the Jar File field and click on the Finish button.
In the OSB console, perform the following steps to import theConfiguration Jar that we just created:
Select the menu System Administration on the left-hand side. You might have to use the scroll bar in order to see all the menu items.
Click on Create in the Change Center to start a new change session.
Click on the Import Resources button and use Browse to select the file created in the export (c:\temp\sbconfig.jar).
Click on the Next button.
Check that the right sources will be imported:
Click on the Import button to start the import.
The successful import is confirmed by the message the import was completed successfully.
Click on the Activate button in the Change Center.
Enter a text describing the changes into the Description field and click on the Submit button to activate the changes.

If we need to adapt some properties like endpoint URI to match the target environment, we can use a customization file and apply that when doing the deployment.

Testing the proxy service through the OSB console

With the OSB configuration deployed successfully to our OSB server, it's time to test it. This recipe will show the most basic way to test, using the OSB console. This is good enough for some initial test but in the long term something more repeatable is necessary. One alternative option is using soapUI, which will be covered in the next recipe.

Getting ready

Navigate to the OSB console and login as the Administrator (that is, weblogic).

How to do it...

In the OSB console, perform the following steps:

Click on the menu item Project Explorer on the left-hand side of the OSB console.
In the project tree, click on basic-osb-service and in the details section on the right, the project folder tree will be shown.
Click on the proxy link.
The proxy service Customer Service should be displayed in the details section (might have to scroll down to see it):
Click on the bug symbol in the Actions section (highlighted in red in the preceding screenshot) to open the test window for the Customer Service proxy service.
In the Proxy Service Testing window, make sure you select the right operation in the Available Operations drop-down list. We want to test the RetrieveCustomerByCriteria operation.
Change the Payload field as shown in the following screenshot:
Click on the Execute button to run the test. The test results are returned after a while in the same window:
Check that the right customer (with ID = 1) information is being returned by the OSB service.
Scroll down in the window to see the Invocation Trace section. This will show steps that the OSB proxy service has executed and values of the variables during execution:

How it works...

Due to the fact that the interface of the proxy service is clearly defined through the WSDL, the OSB console is capable of showing us a sample test message in the Payload field. If we have a proxy service without a WSDL, then testing that service will still be possible through that window, but there will no longer be a sample message shown, as the OSB console does not know about the structure.

The testing capabilities offered by the OSB console are good for some initial tests or if the execution trace is of value, possibly for debugging if using the graphical debugger is not an option. The limitation of the OSB console for testing is clearly that there is no way to persist a test case to be able to run it again later. By that it's also not possible to automate and repeat testing, for example, to start tests inside a nightly build. For that, soapUI, which will be shown in the next recipe, is much better suited.

Testing the proxy service through soapUI

In the previous recipe, we used the OSB console for testing the proxy service. This is ok to just quickly see, if the service is working. But for automatic and repeatable tests, the OSB console is not the right tool.

One advantage of using standards such as the web service standard and the SOAP-based web services is the fact that we can mix and match products from different vendors. The web service standards are vendor-neutral.

Especially for testing web services, there exists a lot of specialized products from different vendors. soapUI is such a specialized tool, which offers both a free as well as a pro version. The free version supports the testing web services with a lot of convenient functionalities. In this recipe, we will show how to test our simple proxy service through soapUI.

Getting ready

To perform this recipe, soapUI needs to be downloaded and installed. We can get it from here: http://www.soapui.org.

In order to test the service from soapUI, we need to know the WSDL URL of the deployed proxy service. The URL is constructed by the OSB at deployment time, based on the location of the OSB server (http://[OSBServer]:[Port]) and the endpoint URI specified in the proxy service (that is, /basic-osb-service/proxy/CustomerService). We need to concatenate the two and add the suffix ?wsdl to get the WSDL URL of the OSB proxy service:

http://localhost:7001/basic-osb-service/proxy/CustomerService?wsdl.

How to do it...

In soapUI, perform the following steps:

In the File menu, select New soapUI Project.
Enter the URL of the WSDL, for the service to be tested (http://localhost:7001/basic-osb-service/proxy/CustomerService?wsdl) into the Initial WSDL/WADL field.
Enter CustomerService into the Project Name field.
Click on the OK buton.
SoapUI will analyze the WSDL and creates a project with some initial requests for all operations defined by the WSDL. Still in soapUI, perform the following steps:
Expand the project in the Navigator on the left.
Double-click on the Request 1 entry of the RetrieveCustomerByCriteria operation.
A new window for the Request 1 will open in the details section.
Replace the ? character in the request message on the left by the input parameter values for the test. The following screenshot shows the request with the ? characters replaced:
Click on the green arrow to start the test.
Check that a valid customer is returned in the response window on the right.
Save the soapUI project so that it is available to use later.

How it works...

Thanks to the standardization through web services, a tool such as soapUI can create the right requests for a service just by analyzing the provided WSDL of the service. SoapUI creates requests for each operation of the service. These requests are persisted in the soapUI project and they can be combined into a test suite. This allows them to be automatically executed, that is, they can be used together with continuous integration.

There's more...

SoapUI is very powerful and it's worth checking the online documentation available on their website (http://www.soapui.org). In any real-live project work, we suggest you to look at the pro version as well. It simplifies a lot of the service testing even further.

Validate that the response is correct

In soapUI, perform the following steps to validate the response from the proxy service against the XML schema in the WSDL:

Right-click on the response message window and select Validate.
Either a pop-up window will appear indicating that the XML message is valid or the validation errors will be displayed in a window below the response message, as shown in the following screenshot:

Creating another request for the same operation

SoapUI supports more than one request per operation, so that a request can be created for each test case to be executed. It's recommended to properly name the different requests in order to be able to identify them later and to clearly indicate the case tested by a given request.

To rename a request, just right-click on the request and select Rename.

An existing request can also be cloned. This reduces the amount of work necessary to correctly set up all the information in the request message. To create a copy of a request, right-click on the request and select Clone Request.

To create a new request from scratch, right-click on the operation and select New request.

Creating proxy service with a WSDL based interface

In the previous recipe, we have created an OSB service with a pass-through proxy service, which offered the same SOAP-based interface as the external service.

In this recipe, we will create a proxy service Customer Management which uses its own WSDL (CustomerManagement) to define a SOAP-based web service interface to its consumers:

Getting ready

Make sure that you have the basic-osb-service project from the previous recipes available in Eclipse OEPE. We will start the recipe from there. If needed, it can be imported from here: \chapter-1\getting-ready\pass-through-proxy-service-created. Delete the pass-through proxy service by right-clicking on CustomerService.proxy, selecting Delete, and then confirm the deletion by clicking on the OK button.

How to do it...

In order to create the proxy service, we need to define the service interface (WSDL) for that new service. We won't create the WSDL in this recipe. The WSDL file and the corresponding XML schema files are available in the \chapter-1\getting-ready\definition\xsd\ folder.

We start this recipe by first copying the WSDL and the corresponding XML schema files into the OSB project, and then create the new proxy service.

In Eclipse OEPE, perform the following steps:

Copy the Customer.xsd and CreditCard.xsd files from the \chapter-1\getting-ready\definition\xsd folder into the xsd folder of the project.
Copy the CustomerManagement.wsdl from the \chapter-1\getting-started\definition\wsdl folder into the wsdl folder in the OSB project.
Make sure that the project looks like the following screenshot (you might need to hit F5 to refresh the project in Eclipse OEPE):
With the WSDL file in place, we can create the proxy service. Still in Eclipse OEPE, perform the following steps:
Right-click on the proxy folder and select New | Proxy Service.
Enter CustomerManagement for the name of the proxy service into the File name field and click on the Finish button.
The new proxy service artifact is created and the proxy service window is shown, with the General tab with the focus on.
We want to create a proxy service with a WSDL interface, so let's select the option WSDL web service and click on the Browse button.
In the pop-up window, expand the project tree and navigate to the CustomerManagement.wsdl file in the wsdl folder.
Click on the node to expand it and select the CustomerManagementSOAP port.
Click on the OK button:
Click on Yes, on the confirmation dialog to overwrite the transport settings with the values from the WSDL.
Navigate to the Transport tab and check the Endpoint URI field. This value will be needed when invoking the service or when consuming the WSDL of the proxy service when deployed on the OSB server.
Click on the Message Flow tab to view the actual message flow:

How it works...

So far the message flow only consists of the interface, which is based on the WSDL. The flow logic itself is empty. If no further actions are added to the message flow, the proxy service works in an 'echo mode'. All the request messages sent to the proxy service are returned unchanged.

Try it by deploying the project to the OSB server and test it through the console or soapUI. To use soapUI for that, create a new soapUI project and import the WSDL. It should be available from here: http://[OSBServer]:[Port]/basic-osb-service/proxy/CustomerManagement?wsdl.

The following screenshot shows the behavior of the 'echo proxy service', when invoked from soapUI:

This is not the behavior that we want from our proxy service. In the next recipe, we will add a Routing action to the message flow, so that the business service the external service is called.

Use the echo behaviour to implement a simple mock service

The echo behaviour seems to be strange at the beginning and it's hard to find a use case in the way just shown. But it's good to see and know that the message flow just returns if there are no (more) actions to execute. Whatever the $body variable holds at that time is returned as the response message.

This behaviour can be used to implement a very simple mock service.

A mock service is a service which simulates the behaviour of the real service or part of it. If we have the WSDL but not yet an implementation, we can create a proxy service and due to the echo behaviour, all we need is an assignment to the $body variable (to set up the response), just before the request message is passed back. This can be achieved by a Replace or Assign Action inside a Pipeline Pair Node/Stage pair.

We can also use soapUI to implement mock services. SoapUI provides a lot of functionality to implement very flexible mock services.

Using a routing action to statically route to another service

To route the message to another service (to a business service or even to another proxy service) a routing action inside a Route node needs to be used.

Getting ready

Make sure you have the current state of the basic-osb-service project available in Eclipse OEPE. We will start this recipe from there. If necessary, it can be imported from here: \chapter-1\getting-ready\echo-proxy-service-created.

How to do it...

In Eclipse OEPE, perform the following steps:

Drag a Route node from the Design Palette and drop it on the message flow path below the interface. A green circle indicates that the item can be dropped here:
Rename the Route node to RouteToCustomerService.
Drag a Routing action from the Communication section of the Design Palette into the Route node:
In the Properties of the Routing action click on the Browse button next to the Service field and select the business service CustomerService.biz (to be found in the business folder).
In the Invoking drop-down list, select RetrieveCustomerByCriteria as the operation to be called:
Click on the Save button.

How it works...

We have created a single route to the operation RetrieveCustomerByCriteria of the external web service. But we not only have one operation on the proxy service to implement, our WSDL contains two operations, which we need to route to different operations on the external service. Therefore, just a single Routing action is not enough. We need to use an Operational Branch with a branch containing a different Routing action. Using an Operation Branch node will be shown in the next recipe.

We cannot select the Use inbound operation for outbound option, because the WSDL on the proxy service is no longer the same as the one on the business service (external service), that is, the operation names do not match.

Adding an operational branch to support the different WSDL operations of the proxy service

To support the different operations of the WSDL we need different branches, which will hold the necessary flow logic. This can be achieved with an Operational Branch node.

Getting ready

Make sure you have the current state of the basic-osb-service project available in Eclipse OEPE. We will start this recipe from there. Delete the existing routing node by right-clicking on it and then select Delete. We again have an empty message flow to start with. If needed, it can be imported from here: \chapter-1\getting-ready\echo-proxy-service-created.

How to do it...

Drag an Operational Branch node from the Design Palette on the right and drop on the Message Flow below the interface.
Change the name of the Operational Branch node to HandleOperationBranch, by editing the Name field in the property window.
The branch node contains two branches, one for the operation FindCustomer and the Default branch. We need one more branch for the StoreCustomer operation.
Click on the + symbol in the upper-right corner of the operation branch and a new branch is added and selected:
Navigate to the Properties tab of the new branch and change the Operation in the drop-down list to StoreCustomer.
Drag a Route node from the Design Palette and drop it on the FindCustomer branch.
Drag another Route node from the Design Palette and drop it on the StoreCustomer branch.
Rename the Route nodes to FindCustomerRoute and StoreCustomerRoute.
Drag a Routing Action from the Communication section of the Design Palette to both Route nodes:
In the Properties of the Routing action, inside the FindCustomerRoute, click on Browse next to the Service field and select the business service CustomerService.biz (to be found in the business folder).
In the Invoking drop-down list, select RetrieveCustomerByCriteria as the operation to be called.
Repeat steps 8-10 for the Routing action of the StoreCustomerRoute, but this time select the CreateNewCustomer in the Invoking drop-down list.
Click on the Save button.

How it works...

The operational branch allows for implementing each operation of a multi-operational WSDL in a different way. In the Message Flow that we have implemented so far, the difference was just the routing to another operation on the external service. If the WSDL only contains one operation, then an operational branch is not really necessary. But we suggest to always use it from the beginning, in order to be prepared if an additional operation is added later. This also provides an option to handle invalid invocations or unsupported operations in the default branch.

With that in place, the service will now correctly route the calls on the different operations. What is not yet done is the adaption between the data models of the two services. This will be covered in the next recipe.

There's more...

In this section, we will discuss the default branch of an Operational Branch node and show how to handle an operation which is not (yet) supported.

Do I have to implement a branch for each operation?

Each single operation does not need to have its own branch. If an operation has no branch, then a call on that operation will end up in the default branch and all calls to an operation without a dedicated branch have to be handled there. If the default handler is left empty, then the behaviour will be an echo, similar to the empty proxy service that we have seen a few recipes back. So every message sent on an operation without a branch will be sent back untouched and unchanged.

The default branch can be used to either generically handle all other messages not handled by a specific branch or to return an error, that this operation is not (yet) supported (see next section).

How to handle operations which are not yet supported?

Use the default branch to raise an error by performing the following steps:

Drag a Pipeline Pair node from the palette and drop it on the Default branch flow.
Rename the pipeline pair to HandleUnsupportedOpsPipelinePair.
Drag a Stage node from the pallet and drop it on the Request Pipeline flow.
Drag a Raise Error action from the design palette and drop it into the stage flow.
Enter the error-code into the Code field and a meaningful error message into the Message field:

An operation branch should not be left empty just because it will only be implemented later and is not supported with the current release. If a branch is empty, then it will have the 'echo' behavior, resulting in a message sent to such an operation being returned just as is. It might be very difficult for a potential caller of such an operation to find out what happened. It's better to remove the branch completely and let the Default branch handle it or to add a Raise Error to the operational branch to signal an error:

When using a branch specific for each operation, the name of the operation can be specified in the error message. If somebody is using the not yet supported StoreCustomer operation, the following SOAP fault will be returned:

Using an XQuery transformation to map between the different data models of the services

Due to the fact that on the proxy service we use a different WSDL than the external service offered, we need to adapt the data models between these two interfaces when sending the request message as well as on the way back when returning the response message. There are different ways to achieve that, probably the most common one in OSB being the use of an XQuery script.

Getting ready

Make sure that you have the current state of the basic-osb-service project available in Eclipse OEPE. We will start this recipe from there. If necessary, it can be imported from here: \chapter-1\getting-ready\operational-branch-proxy-service-created.

How to do it...

First we will need to create the transformation for the request message to be passed to the external service, which has not many data elements to transform.

Create a new XQuery script by right-clicking on the transformation folder in the Project folder and then select New | XQuery Transformation.
Enter TransformFindCustomerRequest into the File name field and then click on Next.
In the Available Source Types tree, select the source type for the transformation: FindCustomer from the CustomerManagement.wsdl.
Click on the Add button to add it to the Selected Source Types, as shown in the following screenshot:
Click on the Next button.
In the Available Target Types tree, select the target type for the transformation: RetrieveCustomerByCriteria from the CustomerService.wsdl.
Click on the Add button to move it to the Selected Target Types.
Click on the Finish button.
Click on Yes to confirm switching to the XQuery Transformation perspective.
The graphical XQuery transformation editor opens, with the source on the left and the target structure on the right. We can now start mapping source to target values. In the case of the FindCustomer request, the target side is a generic query operation with a list of criteria elements. In this recipe, we will only map the ID, assuming that at the moment only the ID value needs to be supported. To map it, follow the ensuing steps:
Right-click on the criteriaField node on the right side (target) and select Create Constant.
Enter id into the Constant Value field of the pop-up window.
Click on the OK button.
The criteriaField is annotated with a little c, indicating that a constant is specified.
Select the criteriaValue on the right side and click on the Target Expression tab (make sure that the XQuery Transformation perspective is active, otherwise the Target Expression tab will not be available).
From the available XQuery Functions on the left, drag the string Type Conversion Functions to the expression editor. The expression will read xs:string($item*-var).
Drag the ID element from the Source type and replace the $item*-var parameter value within the parentheses:
Click on Apply on the left of the Target Expression tab window to accept the expression and a line for the mapping should be displayed. The small f on the criteriaValue node indicates the usage of an XQuery function:
Save the XQuery script
The transformation for the request of the findCustomer operation is now ready to be used. Before we will apply it in the Messagse Flow, let's create the transformation for the response message. Perform the following steps:
Repeat steps 1-10 with the following differences:
- Name the XQuery TransformFindCustomerResponse
- Select the RetrieveCustomerByCriteriaResponse element of the CustomerService WSDL as the source type of the transformation
- Select the FindCustomerResponse element of the CustomerManagement WSDL as the target type of the transformation
Map the source to the target values in the XQuery Transformation editor as shown in the following screenshot. The ID value cannot be directly mapped, a type conversion using the xs:long function is needed:
Now with the two XQuery transformations in place, let's use them in the message flow.
Switch to the Oracle Service Bus perspective.
Open the CustomerManagement proxy service and click on the Message Flow tab.
Drag a Replace action from the Message Processing section of the Design palette into the Request Action of the Routing for the FindCustomer operatin:
Select the Replace action and click on the Properties tab to show the properties of the Replace.
Enter body into the In Variable field.
Click on the <Expression> link.
In the Expression Editor pop-up, click on the XQuery Resources tab.
Click on Browse and select TransformFindCustomerRequest.xq from the transformation folder.
Click on the OK button.
Drag the FindCustomer node on the right side and drop it onto the Binding Variables field. The value of the binding should read $body/cus:FindCustomer.
Click on the OK button.
Select the radio button Replace node contents.
Save the changes.
We have added the transformation of the request message. Let's repeat the same steps for the response message:
Drag a Replace action from the Message Processing section of the Design Palette into the Response Action of the Routing for the FindCustomer operation.
Select the Replace action and click on the Properties tab to show the properties of the Replace.
Enter body into the In Variable field.
Click on the Expression link.
In the Expression Editor pop-up click on the XQuery Resources tab.
Click on Browse and select TransformFindCustomerResponse.xq from the transformation folder.
Click on OK.
Enter $body/ext:RetrieveCustomerByCriteriaResponse into the Binding Variables field. An error is shown because the namespace alias ext is not defined. Click on OK.
Select the radio button Replace node conents.
Click on the Namespaces tab on the left of the Properties window.
Click on Add.
Enter ext into the Prefix field and http://www.crm.org/CustomerService/ into the URI field.
Click on OK.
Save the proxy service and close it.
Deploy the project to the OSB server by right-clicking on the server and select Publish.
Use soapUI to test the behavior of the service. The following screenshot shows the result of successfully executing a test containing the find result of the external service:

The request as well as the response message in the soapUI test window represents the format defined in the Customer Managemen WSDL.

How it works...

We have used two standalone XQuery scripts to define and execute the transformation of the request as well as the response message. XQuery is a very efficient way of executing such transformations.

We have used a Replace action to do each of the two transformations. This allows doing the transformation and assignment to the body variable in one single action. The setting Replace node contents is important because it takes care of the wrapping of the information returned by the transformation inside a <soap-env:Body> element.

The transformation could also be done with an Assign action. But in that case two Assign actions are necessary, the first one doing the transformation into a temporary variable and a second one to wrap the result of the transformation within the <soap-env:Body> element and assign it to the body variable.

Using the Replace action is not only the most efficient way of doing a transformation, it's also the easiest one to use. Therefore, we highly recommend using it if all you need is a transformation from one value to another.

Key benefits

Develop service and message-oriented solutions on the Oracle Service Bus following best practices using this book and ebook
Extend your practical knowledge of building solutions on the Oracle Service Bus
Packed with hands-on cookbook recipes, with the complete and finished solution as an OSB and SOA Suite project, made available electronically for download

Description

Oracle Service Bus 11g is a scalable SOA integration platform that delivers an efficient, standards-based infrastructure for high-volume, mission critical SOA environments. It is designed to connect, mediate, and manage interactions between heterogeneous services, legacy applications, packaged solutions and multiple Enterprise Service Bus (ESB) instances across an enterprise-wide service network. Oracle Service Bus is a core component in the Oracle SOA Suite as a backbone for SOA messaging. This practical cookbook shows you how to develop service and message-oriented (integration) solutions on the Oracle Service Bus 11g. Packed with over 80 task-based and immediately reusable recipes, this book starts by showing you how to create a basic OSB service and work efficiently and effectively with OSB. The book then dives into topics such as messaging with JMS transport, using EJB and JEJB transport, HTTP transport and Poller transports, communicating with the database, communicating with SOA Suite and Reliable Message Processing amongst others. The last two chapters discuss how to achieve message and transport-level security on the OSB.

What you will learn

Create a simple service on the OSB Work efficiently with the Eclipse OEPE Send and consume messages through the JMS transport, covering both topics and queues Learn how to use the HTTP transport to work in a RESTFul way, both from the consumer and provider side Use the Email transport to send and receive emails and process an attachment Use the JCA adapter framework with OSB in order to support communication with a database Use the SB transport to communicate with the SOA Suite Implement reliable communication with the OSB Includes tips and tricks for implementing the message processing in the message flow of a proxy service Learn how to secure OSB services through OWSM.