Tutorials

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Tutorial 3. Validating a Loan Application

Oracle Service Bus proxy services can be configured to validate messages passed between clients and business services. Validation actions can be configured at any stage in the message handling pipeline. However these actions are usually configured in the early stages to eliminate erroneous messages. XQuery conditional expressions can be used to perform explicit validation during message processing.

You can configure message validation logic in the following ways:

This tutorial includes the following topics:

 

Prerequisites

You must complete Tutorial 1. Routing a Loan Application and Tutorial 2. Transforming a Loan Application before beginning this tutorial:

 

Tutorial Objectives

The objective of this tutorial is to provide tasks to configure Oracle Service Bus resources that implement message validation and error handling, in Oracle Service Bus Console. This tutorial includes the following:

Features Highlighted

This tutorial exposes you to the following features of Oracle Service Bus:

 

Definition of the Scenario

A primary mortgage company routes every loan application through an Oracle Service Bus proxy service that validates the message. If the application is:

Figure 5-1 summarizes the logical architecture to support this scenario and illustrates how Oracle Service Bus is positioned in the enterprise system environment to mediate the messaging between the client and the business services.

Figure 5-1 Validating a Loan Application using Oracle Service Bus

Validating a Loan Application using Oracle Service Bus

Overview of the Run-Time Process in Oracle Service Bus

In this scenario, you can configure Oracle Service Bus to validate an incoming message in the message flow against a schema definition in a WSDL resource. Every field is checked for valid content. All elements must be populated for the application to be valid. When the value of the loan duration field is not an integer, the validate action raises an error. The context variable, $fault, is populated with the error details.

The error is trapped by a stage error handler which replaces the body context variable <Notes> field value with the text of the $fault <reason> element. A Report action then saves the error code and the message body, for later viewing and searching in the console. The Reply action returns the body context variable to the client.

In this scenario, the message routing is as follows:

Required Resources

Use the MortgageBroker project folder and the directory structure that you created in the previous tutorial to hold the project artifacts. The resources required for this scenario are described in the following table.

Table 5-1 Routing a Loan Application Tutorial Resources
Resource Name
Description
normalLoan
The WSDL resource.
NormalLoan
The external business service used by Oracle Service Bus.
LoanGateway3
The Oracle Service Bus proxy service.

 

Tasks in This Tutorial

In this tutorial, Oracle Service Bus is used to route a loan application within a mortgage company to a target Web service. The loan application has to be completed correctly for the application to be processed. If there is an error in the application, Oracle Service Bus raises a validation exception, and returns an error message to the client.

You will create a proxy service, LoanGateway3, and configure it to route a message to the NormalLoan business service. You will configure the behavior of the proxy service by performing the following tasks:

Prepare Your Environment

Ensure that Oracle Service Bus is running in the domain you created for the tutorial and that you have completed the tasks described in Tutorial 1. Routing a Loan Application.

Create a Session

For this tutorial, use the MortgageBroker project folder and the directory structure you created in Tutorial 1. Routing a Loan Application to hold the project artifacts.

  1. Click Create in the Change Center to create a new session.
  2. In the Oracle Service Bus Console navigation pane, select the Project Explorer.

    3. The Project Explorer pane is opened in the navigation pane and a project page is displayed in the console.

  3. In the Project Explorer expand the MortgageBroker project tree to expose the subfolders containing the project artifacts:
    • BusinessService
    • ProxyService
    • WSDL

Create the Resources

In this section, you will create the proxy service, LoanGateway3. You will use the existing normalLoan WSDL resource to validate the content of the message. If the loan application is valid and meets the expected criteria it is routed to the existing NormalLoan business service. The normalLoan WSDL resource and the NormalLoan business service were created in To Create the normalLoan WSDL Resource section in Tutorial 1. Routing a Loan Application.

Create a Proxy Service

In this task, you create a LoanGateway3 proxy service that is used to route the loan application to the appropriate business service. For creating this proxy service instance, follow the tasks described in To Create the Proxy Service, and use the proxy service name and the endpoint URI specified in Table 5-2.

Table 5-2 LoanGateway3 Proxy Service Configuration Settings
Proxy Service Name
LoanGateway3
Service Type
Select normalLoan WSDL, helloPort
Endpoint URI
/loan/LoanGateway3

While configuring the proxy service, accept the default settings for the HTTP transport configuration, message level security configuration, and default SOAP Body Type operation selection algorithm. When the Create a Proxy Service - Summary page is displayed, review the summary of configuration settings before to registering the proxy service, and click Save.

When you complete this task, the MortgageBroker/ProxyService folder must contain the following proxy services you created in this tutorial and the previous tutorials:

Configure the LoanGateway3 Proxy Service

The proxy service is implemented in Oracle Service Bus as a message flow. Oracle Service Bus message flows define the implementation of proxy services using request and response pipelines. Message flows can include zero or more of the following pipeline pairs:

Each pipeline can include one or more stages, which in turn include actions.

To configure the behavior of the LoanGateway3 proxy service, you must complete the following tasks:

Create a Pipeline Pair

  1. In the Oracle Service Bus Console navigation pane, select the Project Explorer.

    2. The Project Explorer pane is opened in the navigation pane.

    Note: You must be in a session to edit resources. If you have not already done so, begin a session (click Create in the Change Center) so that you can configure the proxy service and edit the message flow.
  2. In the Actions column associated with the LoanGateway3 proxy service, click the Edit Message Flow icon.

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

  3. Click the LoanGateway3 node, then select Add Pipeline Pair.

The PipelinePairNode1 is created and placed in the message flow. Request and response pipelines are displayed for this node as shown in Figure 5-2.

Figure 5-2 Add Pipeline Pair

Add Pipeline Pair

Configure the Request Actions for the LoanGateway3 Proxy Service

You must now configure the Request actions for the proxy service.

  1. Click the Request icon, then select Add Stage.
  2. Click Stage1, then select Edit Name and Comments.
  3. Enter validate loan application in the Name field and click Save.
Configure an Action to Perform Message Validation
  1. To edit the stage, click validate loan application, then select Edit Stage. The Edit Stage Configuration page is displayed.
  2. Select Add an Action, then select Message ProcessingArrow symbolValidate from the drop-down list. The Validate action is added to the stage.
  3. In the Validate statement, click the <XPath> link to edit the XPath expression. The XPath Expression Editor is displayed.
  4. Click Variable Structures. The Variable Structures pane is displayed.
  5. In the Variables Structure pane, from the Select Structure drop-down list, select body.

    6. A structural representation of the body element is displayed in the Variables Structure pane.

    1. Expand the processLoanApp request element to expand the element.
    2. Click + to expand the loanRequest element.

      3. A graphical representation of the structure of the loan application document is displayed.

      Figure 5-3 Variable Structures Pane

      Variable Structures Pane

    3. Drag and drop icon associated with the loanRequest element, in the XQuery Expression text box. The XQuery expression is written in the text box.

      4. ./exam:processLoanApp/loanRequest

      Figure 5-4 XQuery Expression Editor


      XQuery Expression Editor

      Note: The drag-and-drop functionality works only in Internet Explorer (IE) browsers. If you are using a browser other than IE, select the loanRequest element in the Variable Structures pane. The expression is displayed in the Property Inspector palette. Copy the expression in the palette and paste it in the XQuery Expression text box.
  6. Click Validate to validate the XQuery, then Save.

    7. The Edit Stage Configuration page displays <XPath> which is replaced by the XQuery expression.

  7. In the variable text field, enter body.
  8. Click <Resource> and select WSDL from the list. The Select a WSDL page is displayed.

    9. You must validate the message against the resource since the proxy service is based on the WSDL resource that you originally created.

  9. In the Select a WSDL page, select the normalLoan WSDL resource.

    10. The Select WSDL Definitions pane is populated with the content categories of the WSDL.

    1. In the Select WSDL Definitions pane, from the Types category, select the WSDL type for this WSDL as loanStruct.
    2. Click Submit to complete the selection.
  10. Select the Raise Error on validation failure option. The Validate action will be displayed as shown in Figure 5-5.
    11. Figure 5-5 Configured Message Validate Action


    Configured Message Validate Action

  11. Click Save to save the configuration.
Note: Message validation must be done as early as possible in a message flow. This prevents unnecessary processing of invalid message content. By raising an exception, further message processing is stopped and an error response is immediately returned to the client.
Note: Messages can be validated at the route node or using a separate Validate action (as in this case). When you create a Validation stage, message processing is more modular since the configured validate actions logically break down the message flow. If multiple validations are performed on a message, the validate action is logically expanded.
To Configure the Stage Error Handler

You must perform the following tasks to configure the Stage Error Handler:

Add Stage Error Handler Element
  1. Click the validate loan application stage, then select Add Stage Error Handler. The Edit Error Handler page is displayed.
  2. Click Error Handler, then select Add Stage. The stage1 node is displayed.
    3. Figure 5-6 Add Stage Error Handler


    Add Stage Error Handler

  3. Click stage1 and select Edit Name and Comments.
  4. Change the stage name to Reply, then click Save.

    5. The Edit Stage Configuration page is displayed.

  5. To edit the stage, click Reply, then select Edit Stage.
Add an If...Then… action to the Stage Error Handler
  1. Select Add an Action > Flow Control > If... Then...

    2. The If...Then action is added to the Reply stage.

  2. Click the If...Then… action <Condition> link to specify the expression that needs to be validated. The Xquery Condition Editor page is displayed.
    1. Select the Builder pane.
    2. In the Comparison Expression pane within the Expression Builder pane, enter $fault/ctx:errorCode in the Operand textbox.
    3. Select the = Operator from the drop-down list.
    4. Enter “BEA-382505” (including double quotes) in the Value pane.
    5. Select the radio button for the And conjunction.

      6. The Expression Builder pane is displayed as in Figure 5-7:

      Figure 5-7 Conditions in the Expression Builder


      Conditions in the Expression Builder

    6. Click Add to add expression to the Expressions textbox.
      7. Figure 5-8 Expressions Textbox


      Expressions Textbox

  3. Click Save to save the expression and return to the Edit Stage Configuration page.
Add a Replace Action to the Stage Error Handler
  1. To add a Replace, click Add an Action > Message Processing > Replace within the then... portion of the If...Then action.
    2. Note: When adding multiple actions on a page, click the action preceding the placement of the new action and select the action to be added from there. actions are added in sequence.

    The replace statement is displayed as shown in Figure 5-9.

    Figure 5-9 Replace Statement


    Replace Statement

  2. In the Replace statement, click the <XPath> link to edit the XPath expression. The XPath Expression Editor page is displayed.
  3. In the Variable Structures pane, select body from the Select Structure drop-down list.

    4. A structural representation of the body element is displayed in the Variable Structures pane.

    1. Expand the processLoanApp request elements.
    2. Select the icon associated with the Notes element of $body, drag and drop it on the XPath expression text box. The following XPath expression is written in the text box.
      3. ./exam:processLoanApp/loanRequest/java:Notes

      In browsers other than Internet Explorer, copy and paste the expression from the Property Inspector pane.

      Figure 5-10 Replace Statement XPath Expression


      Replace Statement XPath Expression

  4. Click Validate, then Save.
  5. In the variable text field, enter body.
  6. Click the <Expression> link to display the XQuery Expression Editor page.
  7. In the XQuery Text pane, enter: $fault/ctx:reason/text()
    8. Figure 5-11 Replace Statement XQuery Expression


    Replace Statement XQuery Expression

  8. Click Validate, then Save.
  9. Select Replace node contents option. You need not replace the entire node.

    10. The Replace action is displayed as shown in Figure 5-12.

    Figure 5-12 Add Error Handler Using Replace Action


    Add Error Handler Using Replace Action

Add a Report Action to Report the Error

Next, you must add a Report action and configure it to report the body context variable as detailed context, and set a key name of errorCode and the key value to the actual error code found in the fault context variable.

  1. Click the Replace icon and select Add an ActionArrow symbolReportingArrow symbolReport. The report action is added to the page.
  2. In the Report statement, click the <Expression> link. The XQuery Expression Editor page is displayed.
  3. In the Variables Structures pane, select body from the Select Structure drop-down list.
    1. Select the icon associated with the $body - ProcessLoanApp (request) element and drag and drop it on the XQuery Expression text box.

      2. The $body XQuery expression is entered in the text box.

      Note: The drag-and-drop functionality works only in Internet Explorer (IE) browsers. If you are using a browser other than IE, select the body element in the Variable Structures pane. Copy the expression from the Property Inspector pane and paste it in the XQuery Expression text box.
    2. Click Validate, then Save.

      3. The Edit Stage Configuration page is displayed.

  4. In the key-value pair table, click the Add a Key link.
    1. Enter a Key Name of errorCode.
      2. Figure 5-13 Report Action Expression Key


      Report Action Expression Key

    2. In the Key Value field, click <XPath> link. The XPath Expression Editor is displayed.
  5. In the Variable Structures pane, select fault from the Select Structure drop-down list.
    6. Figure 5-14 Fault Variable Structure


    Fault Variable Structure

    1. Drag and drop the icon associated with the errorCode in the XPath Expression text box.

      2. Type ./ctx:errorCode expression in the text box.

      Note: The drag and drop functionality works only in Internet Explorer (IE) browsers. If you are using a browser other than IE, select the errorCode element in the Variable Structures pane. The expression is displayed in the Property Inspector palette. Copy the expression and paste it into the XPath Expression text box.

      This step enables you to index the reporting data by error code. The keys are a convenient way to identify a message. You can use the error code to search for reporting entries in the reporting module.

  6. Click Validate, then Save.
  7. In the variable text field, enter fault.

The Report action must be displayed as shown in Figure 5-15.

Figure 5-15 Configured Report Action

Configured Report Action

The Edit Stage Configuration page is displayed as shown in Figure 5-16.

Figure 5-16 Request Actions for LoanGateway3 Proxy Service

Request Actions for LoanGateway3 Proxy Service

Add an Else Action to the Stage Error Handler
  1. Click the If...Then… icon.
  2. Select Add else Condition to add an Else action to the stage error handler.
Add a Replace Action Within the Else Action
  1. Select Add an Action > Message ProcessingArrow symbolReplace.
  2. Execute the steps in the Add a Replace Action to the Stage Error Handler section.
Add a Log Action Within the Else Action
  1. Click the Replace icon within the Else action.
  2. Select Add an Action > ReportingArrow symbolLog.

    3. The Log action is displayed.

    Figure 5-17 Reporting Log Action
  3. Click the <Expression> link to display the XQuery Expression Editor page. Enter $fault/ctx:reason/text() in the XQuery Text page.
  4. Click Validate and Save to validate and save the expression and return to the Edit Stage Configuration page.
  5. Enter Other than validation error in the “with Annotation” text box.
  6. Select Error from the “at severity level” drop-down list.

The completed Else condition must be displayed as shown in Figure 5-18.

Figure 5-18 LoanGateway3 Proxy Service Request Else Actions

LoanGateway3 Proxy Service Request Else Actions

Add a Reply Action to Reply with a Failure Code
  1. Click the Report icon under the If...Then action.
  2. Select Add an ActionArrow symbolFlow ControlArrow symbolReply. The reply action is added to the page.
  3. Select With Failure option. The Report Reply action is displayed as shown in Figure 5-19.
    4. Figure 5-19 Report Reply Action with Failure Code


    Report Reply Action with Failure Code

  4. Click Save to save the stage configuration and return to the Edit Error Handler page.
  5. Click Save to save the error handler configuration.

Add a Default Routing Case

You must now add a Route Node to the Pipeline pair and configure it to enable default routing to the NormalLoan business service.

Configure the Route Node
  1. Click PipelinePairNode1, then select Add Route.

    2. The Edit Message Flow page is displayed.

  2. Click RouteNode1, then select Edit Route. The Edit Stage Configuration page is displayed.
  3. Click Add an Action, then select CommunicationArrow symbolRouting.

    4. The Route to action is displayed in the Edit Stage Configuration page as shown Figure 5-20.

    Figure 5-20 Route to Statement


    Route to Statement

  4. In the route statement, click the <Service> link to define the service to which you want to route messages. The Select Service page is displayed.
    1. Select the NormalLoan business service, then Submit.
  5. In the Operation drop-down list, select processLoanApp.
  6. Click Save.

    7. This is the operation on the NormalLoan business service that is invoked at run time. You have now defined the case for routing the loan application to the NormalLoan business service. The Edit Message Flow page is displayed as shown in Figure 5-21.

    Figure 5-21 LoanGateway3 Proxy Service Message Flow


    LoanGateway3 Proxy Service Message Flow

  7. Click Save to save the configuration and return to the MortgageBroker/ProxyService page.
  8. Click Activate, then Submit.

To Test the Loan Application Routing Configuration Using Test Console

Now that you have configured Oracle Service Bus to work with the client and the target business services, you must test the configuration. To test the routing configuration, you must change the value of the Loan duration (in years) field in the build.xml file. Then you must test the routing logic by verifying whether the proxy service behavior changes for different loan values.

If the loan value entered is a non integer, an exception must be triggered and an error message displayed in the Notes field of the message. If the loan value entered is an integer, the message must be routed to the NormalLoan business service. The message returned in the command window indicates whether a validation exception occurred or the message was routed to the appropriate business service.

To test the loan application using the test console, you must first deploy the client jars in the WebLogic Server console. For more information see, Load the Client Application.

To test the Validation of the Loan Application by LoanGateway3

Scenario One
  1. Start WebLogic Server in ServiceBusTutorial Domain.
  2. In Oracle Service Bus Console, make sure the session is activated.
  3. Click on Resource Browser > Proxy Services in the left panel.
  4. Click the Launch Test Console icon in Actions column for LoanGateway3 to launch the test console.
  5. Replace the default payload in loanRequest field with the following code:
    6. <loanRequest xmlns:java="java:normal.client">
        <!--Optional:-->
        <java:Name>Smith</java:Name>
        <!--Optional:-->
        <java:SSN>1234567</java:SSN>
        <!--Optional:-->
        <java:Rate>5</java:Rate>
        <!--Optional:-->
        <java:Amount>900000000</java:Amount>
        <!--Optional:-->
        <java:NumOfYear>10.1</java:NumOfYear>
        <!--Optional:-->
        <java:Notes>Large Loan Processing</java:Notes>
    </loanRequest>

Accept other default settings and click Execute. The response as in Figure 5-22.

Figure 5-22 Response from Error Handler

Response from Error Handler

This response message indicates that a validation exception occurred because the loan duration specified was not an integer.

Scenario Two
  1. Start WebLogic Server in ServiceBusTutorial Domain
  2. In Oracle Service Bus Console, make sure the current session is activated.
  3. Click on Resource Browser > Proxy Services in the left panel
  4. Click on Launch Test Console icon in Actions column for LoanGateway1 to launch the test console.
  5. Replace the default payload in loanRequest field with the following code:
    6. <loanRequest xmlns:java="java:normal.client">
        <!--Optional:-->
        <java:Name>Smith</java:Name>
        <!--Optional:-->
        <java:SSN>1234567</java:SSN>
        <!--Optional:-->
        <java:Rate>4</java:Rate>
        <!--Optional:-->
        <java:Amount>300000000</java:Amount>
        <!--Optional:-->
        <java:NumOfYear>10</java:NumOfYear>
        <!--Optional:-->
        <java:Notes>Normal Loan</java:Notes>
    </loanRequest>

Accept other default settings and click Execute. The response as in Figure 5-23.

Figure 5-23 Response From Normal Loan Processor

Response From Normal Loan Processor

The response message indicates that the NormalLoan business service processed the loan application because the loan duration value was an integer.

Step 7: Using Reporting and Monitoring

Now that you have tested the proxy service, you can explore the reporting and monitoring features of the Oracle Service Bus Console.

Note: You must have run the tests in To Test the Loan Application Routing Configuration Using Test Console multiple times (at least five times) to generate data to enable you to explore the reporting and monitoring features.

Reporting

Oracle Service Bus includes a JMS Reporting Provider for message reporting. The Reporting module in the Oracle Service Bus Console displays the information captured from this reporting provider. You can create your own reporting provider using the Reporting Service Provider Interface (SPI) if you do not wish to use the out-of-the-box reporting provider.

The dashboard of Oracle Service Bus Console contains reporting features that are presented in a drill-down format. When you explore the links presented, the information is made available to you.

For more information, see:

Monitoring

Oracle Service Bus can monitor and collect run-time information for both systems operations and business auditing purposes. Oracle Service Bus aggregates run-time statistics that you can view on a customizable Dashboard. The Dashboard allows you to monitor the health of the system and alerts you to problems in your messaging services. With this information, you can quickly and easily isolate and diagnose problems as they occur.

For more information, see:


  Back to Top       Previous  Next