lab2 default-routing v1

Oracle® Service Bus 10gR3

Hands-On Workshop

Lab 2: Default Routing OSB is designed to support common use case patterns out of the box. One of these patterns is called Default Routing. With default routing, messages are routed from a client through the OSB intermediary to the appropriate business service with no message processing. The message that OSB receives is the message that OSB routes. In this lab, OSB is used to route a loan application within a mortgage company to a target web service. Perform the following tasks to design and configure a proxy service and the associated resources in OSB to implement this use case scenario.

Windows Version Lab Two

Prerequisites:

• Completion of Lab One.

Lab Objectives The objective of this lab is to create and test a simple routing scenario using the graphical environment provided in OSB Console. It includes the following tasks:

• Create A Project Structure and Register a WSDL Resource • Create A Proxy Service From A WSDL Resource • Test A Proxy Service Default Configuration • Register and Test a Business Service • Configure A Route Node And Test A Default Routing Scenario

This lab introduces you to:

• Project Model • Proxy And Business Services • Resource Creation • Message Flows • Echo Function • Route Node • Resource Deletion And Recovery • Test Console

Definition of the Scenario A primary mortgage company uses OSB to route all received loan applications to a business service for processing. From the design pattern perspective, this is an example of a default routing use case. In a default routing use case a proxy service receives a message and unconditionally dispatches it to a business service, untouched. Figure 1-1 summarizes the logical architecture to support this scenario. It illustrates how OSB mediates the messaging between the clients and the business services in your enterprise.


2

Figure 1-1 Expose a Loan Application Request Web Service via OSB

Overview of the Run-Time Process in OSB A client sends a loan application to a proxy service named LoanGateway1. The default proxy service has a route node that unconditionally routes the loan application document to the NormalLoan business service. The target business service returns a response similar to the following :


3

Main Resources The following table lists the main resources that will be created or used in this lab:

Resource Name Description

normalLoan This is the WSDL resource.

NormalLoanProcessor This is business service used by OSB.

LoanGateway1 This is the OSB proxy service.

Table 1-1 Default Routing Loan Application Lab Resources

Tasks in This Lab In this lab, OSB is used to route a loan application within a mortgage company to a target web service. Perform the following tasks to design and configure a proxy service and the associated resources in OSB to implement this use case scenario.

Create the "Mortgage Broker" Project Structure and Register a WSDL Resource It is important to have a project structure to organize the project artifacts appropriately. The "project" is a directory structure that is flat or nested. It is best to keep the folder names relatively short because there are resource browser windows that present lists of resources by their full project path name. Long names make it difficult to identify a resource in the resource browser window as the name of the resource may be beyond the resource browser window margin. Note: A project structure which organizes its resources with folders named after the resource type they will house is called a “resource-based project structure”. This project uses a resource-based project structure.

Best Practice: Use short but descriptive folder and project names. The taxonomy of the project should be designed to support the lifecycle of the project artifacts. A “resource based project structure” may not be appropriate for large projects as it does not organize artifacts by how they are used or how they are related, but only by resource type.


4

1. Login to the Oracle Service Bus console through the following url:

http://localhost:7021/sbconsole Username : weblogic Password : weblogic

2. To create a new project, or modify an existing project, or create, modify or register any artifacts in the console, you must start a Change Center "session".

3. Start a new session by clicking the button. The button label changes

to .

For your information…

Change Center Overview

• Within a session you can modify the current configuration but the

configuration will not be moved into production until you click .

• When in a Change Center session you can click and by doing so leave the current session without losing the configuration changes.

• After clicking the button label changes to .

The presence if the button indicates a session has been saved under the

current userid. Click to reactivate a previous Change Center session. The

button label changes back to . If you select at any point you will

‘loose’ the current session changes and then the button text changes back to

.

• When the button is visible it indicates there are no pending configuration changes under the current userid.

4. Create project "Mortgage Broker".


5

http://localhost:7021/sbconsole

• As shown below select the Project Explorer link from the left navigation panel.

• Enter "Mortgage Broker" in the Project Name field and click the “Add Project” button.

Note: If the project named "default" exists, it can be deleted.

5. Create Project Folders under the Mortgage Broker project

• As a first step click the Mortgage Broker project to open it.

• Create three folders within the Mortgage Broker project, one for each of the resource types being defined for the project, as described below. The sequence of steps is :

• Enter the folder name and then

• Click the Add Folder button as shown below.


6

• The three folders to create and name are:

o “Proxy Services”

o “Business Services”

o “WSDL”

When done your project folder structure should look like this:

• your configuration changes. • Submit your changes by clicking the Submit button.


To register a WSDL resource you can import the WSDL or copy and paste the WSDL text into the WSDL text box. In this exercise the WSDL text will be pasted into the WSDL text field.

The WSDL defines the public contract (interface specification) between the client and service, whether the service is a proxy service or business service.

You will create the WSDL resource first as subsequent service registration steps depend on it. It will be used to register a business service and it will be used during proxy service creation.

Each resource is configured using a configuration wizard.

Each configuration wizard consists of a sequence of pages that request information about the resource and provide property configuration options.

The pages are sequentially displayed in the console until the configuration is complete.

6. Register a WSDL Resource


7

- To register a WSDL resource:

• Start a new session. ( )

• Select the WSDL folder from within the Project Explorer folders.

• In Resources, from the Create Resource drop down list, select WSDL as shown below.

• The Create a New WSDL Resource page is displayed. This is the first configuration page for this resource. You begin defining the WSDL resource here. On this page enter the following information:

o Resource Name: normalLoan

o Resource Description (optional): enter a text description of the resource.

o WSDL: Using Browse button, navigate to the WSDL associated with the normal loan process and select it.

This WSDL is here: [OSB_INSTALL_HOME]\osb_10.3\samples\servicebus\examples\src\examples\webservices\jws_basic\normal\NormalLoanApprovalService.wsdl

o Click Save.

o Note: During the Save process the WSDL is validated to verify that it conforms to Oracle Service Bus WSDL specifications.

• your configuration changes. • Submit your changes by clicking the Submit button.


8

Best Practice: Use concise comments that clearly indicate what is being saved. This is very important because each saved transaction can be rolled back and a clear description will help identify and isolate only the changes that need to be rolled back.


Resources can be renamed, moved, cloned and deleted.

Notice these icons in the Options column as shown below.

: Rename : Move : Clone : Delete

7. Next let's delete a WSDL resource then recover it. • Open the WSDL folder.

• Start a new session. ( )

• Delete the WSDL normalLoan by clicking .

Note that no confirmation dialog occurs. A confirmation is not needed because you can easily roll back the resource deletion.

• your configuration changes.

Add a note describing what is being done, such as “delete the normalLoan wsdl”.

• Submit your changes by clicking the Submit button.

• Now the WSDL resource has been deleted. The View Configuration Changes page is displayed.

• Verify that the WSDL resource was deleted by examining the resources in the WSDL folder. There should be no resources in that folder.

• Next prepare to recover the deleted resource by selecting the View Changes link in the Change Center :

•


9

The View Configuration Changes page is displayed.

• Recover the WSDL resource by finding the corresponding configuration change transaction on the View Configuration Changes page.

• Click the undo icon in the Options column of that configuration change.

Note that you did not have to start a session to undo a configuration change. You are allowed to undo changes because you are logged in as the administrative user of the console.

• Verify that the WSDL resource was restored by examining the resources in the WSDL folder. There should be one WSDL resource in that folder.

• Notice that each level (represented by a folder) of a Project includes a mini-dashboard indicating (References:) how many outbound resources are referenced by resources in the current view, and (Referenced By:) the count of inbound references from other resources into resources in this view.

Create an HTTP Proxy Service From a WSDL Resource Create HTTP proxy service LoanGateway1 from WSDL normalLoan using the WSDL Port configuration option.

1. Select the Project Explorer from the navigation panel

2. Select the project MortgageBroker.

The project folder expands to show the directory structure of the project.

3. Select the Proxy Services folder.

4. Start a session by clicking the Create button in the Change Center.

5. In the Create Resource drop down menu, select Proxy Service as shown below.


10

- The Create a Proxy Service - General Configuration page is displayed.

6. Enter the Service Name. In this case enter LoanGateway1.

7. In Service Type select WSDL Web Service.


Service Type Definitions

Messaging Service

A Messaging Service can receive messages of one data type and respond with messages of a different data type. These exchanges can be either request/response or one-way. Unlike Web services, the content-type of the request and response need not be the same. The supported data types include XML, MFL, text, and untyped binary. If one of the request or response messages is non-XML, you must use the messaging service type.

Any SOAP Service

The only information this service type defines is that the service is receiving or


11

sending SOAP messages—regardless of their WSDL binding definition. Therefore the binding configuration for this type is empty. In addition, as there is no binding configuration, the combination of this type and the content-type of the message is sufficient to determine whether or not there are attachments to the message. As per their definition, any services (SOAP or XML) do not have any WSDL definition. It is not possible to request a WSDL document for those services. Services of this type are suitable for (but not limited to) circumstances when the structure of the incoming message is not important. If you want to expose one port to clients for a variety of enterprise applications, use Any Soap or Any XML service types.

Any XML Service

An XML Service is a non-SOAP service. The messages are of any XML structure and can be of any type allowed by the proxy service configuration. If you want to expose one port to clients for a variety of enterprise applications, use Any Soap or Any XML service types.

8. Click Browse.

The WSDL Browser window is displayed.

9. In the WSDL browser, select the normalLoan WSDL.

Once selected the WSDL Definitions panel will automatically be populated with the ports of the WSDL.

10. In the WSDL Definitions panel, select the WSDL port helloPort found in the Ports category then click Submit to complete your selection.


WSDL Port .vs. WSDL binding

A WSDL is not required to have a binding definition and a port definition; it can have just one or the other. That is why both choices exist when creating a proxy service.

Regardless of whether you define a proxy service based on a WSDL port or a WSDL binding, a new WSDL is generated which represents the public interface to the proxy service.

The WSDL generated for the proxy service defines only a single port. If the service is generated from port X in the template WSDL, then port X is also defined in the generated WSDL. Any other ports defined in the template WSDL are not included in the generated WSDL.

Furthermore, if you base the proxy service on a WSDL port, the generated WSDL uses that port name and preserves any WS-Policies associated with that port. The binding is determined from the port, and in turn, the port type is determined from the binding.

If proxy service clients rely on WS-Policy security in the WSDL you should use the port option because the generated WSDL will not have the WS-Policy. This is because a given binding can have multiple ports associated with it and each can use a different URL and have a different WS-Policy and there is no way at this time, when using the WSDL binding option, to choose which port/policy to use. OSB will not include a WS-Policy in the new service-name/port-name

11. At the bottom of the General Configuration page click Next to continue the proxy service configuration process.


12

The Create a Proxy Service - Transport Configuration page is displayed.

12. Accept the default protocol, HTTP.

HTTP is the default protocol as it is the assumed protocol of most services. The list of available protocols for the service depends on the type of service being created. The contents of the transport configuration pages change depending on the transport chosen.

13. Set the Endpoint URI to /loan/gateway1.

You are now defining the URI to which a proxy client will connect. Note that the hostname and port are not required. This is because proxy services are hosted by OSB and therefore OSB knows what the host name and port are.

14. You now have the choice of which headers you want OSB to pass into the proxy service message flow. Accept the default “No” to not pass any headers. Click “Next” to go to the next page.

This is ok to do because for this exercise you are not going to need to use any headers in the message flow.

15. The Create a Proxy Service – HTTP Transport Configuration page is displayed. Accept the defaults. Click “Next” to go to the next page.

- Basic authentication is not required for this proxy service.

- Notice the Dispatch policy selector. The proxy service can be associated with a Work Manager thread pool through this selector. This is a key performance management option. The list of available thread pools on the host server will be displayed in this list.

- The Request message and Response message character set encoding can be specified.

16. The Create a Proxy Service - Operation Selection Configuration page is displayed. Accept the default selection of SOAP body type. Click “Next” to go to the next configuration page

On this page you are selecting the part of the message that identifies the web service operation to invoke on the target business service.

If the clients to this proxy service are HTTP / SOAP clients and the message conforms to the WSDL 1.1 standard convention, the operation selection information is in the SOAP Body.

It is important to note that retrieving operation information from message headers and not the soap body will result in a performance improvement.


13


What is an operation?

An operation in a java web service WSDL corresponds to a public method in the java web service. If more than one method is accessible to a client (that is, there are multiple public methods) then each public method will have an operation definition in the WSDL.

Note: It can be expensive (marshalling/unmarshalling overhead) to process the message body to determine the operation to select.

For better performance have the operation selection information in a header.

Note that Oracle Service Bus does not control where the operation selection information resides. This is a client-side issue.

If the operation information is in a header usually the client side code has created a custom SOAP header or custom WS-Addressing header or custom Transport Header which contains the web service operation information.

Again note that if the operation is not in the SOAP body, you may have to indicate to Oracle Service Bus, with XPath, where the operation resides in the incoming header.

Note also that you must provide at least one mapping between operation values in the header and the available operation names in the proxy service WSDL.

17. The Create a Proxy Service – Message Content Handling page is displayed. Accept the defaults. Click “Next” to go to the next configuration page.

18. The Create a Proxy Service – Summary - General Configuration page is displayed showing a summary of the configuration settings for the proxy service. You can review the configuration settings and edit them if necessary before registering the proxy service. When satisfied with the proxy service configuration settings, select “Save” to create the service.

19. Then select , then Submit, to instantiate the new service configuration.


14

Test A Proxy Service Default Configuration 1. Open the proxy service default message flow and examine it.

(It is assumed you are in the Project Explorer and in the Mortgage Broker Proxy Services directory).

• Select Create in the Change Center to start a session.

• In Options, click the Message Flow icon of the proxy service.

The Edit Message Flow page appears.

Note the single node in the message flow. This node is not configurable; it simply marks the start of the message flow.

A proxy service with a single node echoes the incoming document back to the sender. This is very handy for testing a proxy service without having to dispatch a message to a target service.

• Next right click the node and notice that no OSB context menu appears.

• The OSB web console is strictly a Left click environment, so left click the node and explore the options shown.

• When you are done, click Cancel

• Click Discard to end your session.

2. Run an echo test by sending a message to the proxy service to test its availability. (It is assumed you are in the Project Explorer and in the MortgageBroker Proxy Services directory).

• Navigate to the LoanGateway1 Proxy.

• Click the little green bug to activate the OSB Test Console.

• Take a few minutes to look over the test console. The contents of the test console reflect the service definition.

• You can test proxy services and business services.

• Start at the top of the test page. Check out the Operations list. If the service has multiple operations you would choose the one to test from this list.

• The Test Configuration section Direct Call option, when selected, bypasses the Transport layer of the application server. This is the default.

• Notice the Request Document section. The test console has automatically created an input document based on the proxy service WSDL. You can input your own data here, including SOAP headers and transport parameters and transport headers.

• Open the Transport section. The contents of this section can completely change based on the transport type of the service. For example if the transport is JMS,


15

JMS options appear here.

• To learn more click the Help link at the top right of the test console.

• Click the "Execute" button to send the message to the proxy. o Notice the Request and Response messages are identical.

• Scroll down to the "Invocation Trace"

• Expand the “echoing request" node. o Note that there isn’t any useful information here, it simply says that the

request message was echoed. But if the incoming message had been transformed in some way, you would see the entire trace of everything that happened to the message, its headers etc. You will see this kind of trace later in the training.

• Close the test console

Register and Test an HTTP Business Service Register business service NormalLoanProcessor and base it on WSDL normalLoan using the Port option.

*** Reminder ***

Each time a resource is created, registered or changed a console “session” must be started. Please be sure to create a session when required even if the instructions do not call for it.

To Register a Business Service:

1. Select the Business Services folder in the Mortgage Broker project.

By doing this you are choosing where the new Business Service definition will reside.

2. In the Create Resource drop down menu select Business Service.


16

3. The Create a Business Service - General Configuration page is displayed. Enter the Service Name. In this case enter NormalLoanProcessor.

4. In the Service Type section select WSDL Web Service then click Browse.

The WSDL Browser window appears.

5. Select the normalLoan WSDL.

The Definitions panel is populated with the WSDL details.

6. Select helloPort from the Ports category

7. Click Submit.

8. Click Next to go to the next page.

9. The Create a Business Service - Transport Configuration page is displayed. Accept the default protocol - http.

10. Select none as a Load balancing Algorithm as load balancing is only relevant when a service has multiple end points.

In this case there is only one service uri. Accepting the default behavior or selecting none does not affect the behavior of the proxy service.


17


The field above Existing URI's is the field where you enter additional URI's.

The Delete button to the right of existing URI's causes existing URI's to be deleted.

11. Accept the default values on the rest of the page. Click Next to go to the next page.

12. The Create a Business Service – HTTP Transport Configuration page is displayed. Accept the default settings on this page. Click Next to go to the next page.

13. The Create a Business Service – SOAP Binding Configuration page is displayed. Click Next to go to the next page.

14. The Create a Business Service – Message Content Handling page is displayed. Click Next to go to the next page.

15. The Create a Business Service - Summary page is displayed. You can now review the business service definition to verify that it is correctly configured. You can edit the configuration from this page should you wish to make any changes. Click Save to accept the configuration settings

16. Click Activate and Submit to instantiate the business service. Be sure to add a descriptive note.

Test the business service

1. Navigate to the business service

2. Click the little green bug to activate the OSB Test Console.

- Test the service and evaluate the results.

A successful test response document will be similar to this:


18

3. Close the test console after a successful test.

Configure A Route Node And Run An End to End Pass-Through Routing Scenario Test Add a route node to the LoanGateway1 proxy service. Configure the route node to route to the NormalLoanProcessor business service.

Note: It is assumed the current page is the Project Explorer > MortgageBroker > Proxy Services page and you have created an editing session.

1. Click the Message Flow icon of the LoanGateway1 proxy service.

The Edit Message Flow page for the proxy service LoanGateway1 is displayed.

This page displays the default message flow configuration.

The default configuration consists of a start node.

This is the default and minimum configuration of a message flow.

2. Left click the start node (LoanGateway1). From the pop up menu select Add Route.


19

- The message flow should look similar to this:

3. Left click the route node. From the pop up menu select Edit Name and Comments

4. In the dialog, enter a name "Default Routing" for the route node


20

5. Click Save

6. Left click the route node icon and from the pop up menu select Edit Route.

- The Edit Stage Configuration page is displayed. The page contains a single link,

Add an Action

7. Select the Add an Action link.

The Edit a Stage Configuration page changes to display the actions that can be configure for the stage. The action list is context sensitive. That is, the list of available actions is different for a route node .vs. a stage .vs. an error handler pipeline.

8. Select the Communication - Routing action choice.

The page changes to display the Route node default configuration.


21

Notice the Request and Response action sections.

The Request Action section is where actions are defined to affect outbound (outbound to the business service) message processing.

The Response Action section is where actions are defined to affect messages that the target business service has returned to OSB. Or if the target service does not generate a reply, you can use the Response Message pipeline to create one.

So, the classic execution order :

1. Request Pipeline Actions

2. Route the message and wait for response

3. Response Pipeline Actions.

9. Select the service to route all messages to.

10. Click the <Service> link to bring up the service browser.

11. Select the NormalLoanProcessor service as the routing destination

12. Click Submit.

13. Select the WSDL operation to invoke. There is only one : processLoanApp

Note: In this use case there is no request or response pipeline logic to configure.


22

We are done configuring the proxy service to do ‘default routing’.

14. Click Save All to save the proxy service configuration.

15. Click Activate and Submit in the Change Center to implement the configuration changes.

Test the default routing scenario using the jsp client provided for this lab.

1. Launch the jsp client

http://localhost:7021/examplesWebApp/cs_JWS_WebService.jsp

2. Click “Submit Loan Application” to send a message to proxy service LoanGateway1

A successful end to end test result looks similar to this:

3. Challenge Exercise: Test the use case using the OSB test console.


23

http://localhost:7021/examplesWebApp/cs_JWS_WebService.jsp

lab2 default-routing v1

Documents

osb proxy service

default proxy service

default routing osb

target business service

normalloan business

appropriate business

osb console

osb routes