Tutorials
This section describes how a BEA AquaLogic Service Bus proxy service can be configured to validate a message passing from a client to a business service. Validation can happen at any stage in the flow, though usually it happens as early as possible to prevent further unnecessary processing of the message should an invalid result occur.
Validation can happen in a number of ways:
BEA AquaLogic Service Bus does not automatically validate the message sent or received against the service interface definition, whether this is a WSDL definition or a messaging interface definition. However, you can configure a Validate action and use XQuery conditional expressions to perform explicit validate checks in the message flow. This reduces the possibility of run-time errors as a result of invalid configurations.
This section includes the following topics:
Complete Tutorial 1. Routing a Loan Application and Tutorial 2. Transforming a Loan Application.
The goal of the tutorial is to provide the steps to configure and test BEA AquaLogic Service Bus to demonstrate how message validation and error handling is managed using the graphical environment provided in the AquaLogic Service Bus Console. It includes the following:
Developing this tutorial exposes you to the following features of AquaLogic Service Bus
A primary mortgage company routes every loan application through a BEA AquaLogic Service Bus proxy service which validates the message. If the application is incomplete, it is written to an error directory and an error message is returned to the client. If complete, it is routed to a business service for review. If approved, the service returns a message indicating whether the loan is accepted or rejected.
The following figure summarizes the logical architecture to support this scenario. It illustrates where AquaLogic Service Bus fits in your enterprise to mediate the messaging between the client and the business services.
Figure 5-1 Validating a Loan Application using AquaLogic Service Bus
In this scenario, you will configure AquaLogic Service Bus to validate an incoming message in the message flow against a schema definition in a WSDL resource. Each field is checked for content. All elements must have content for the application to be valid. However, in this case, the validation action raises an error when the value of the loan duration field is not an integer. The context variable, $fault
, is populated with the error. 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, for context, 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, one of the following actions takes place:
NormalLoanApprovalService
, which returns a reply The loan application was accepted
. You will use the Project folder, MortgageBroker
, and the directory structure 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
In this tutorial, BEA AquaLogic 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, then a validation exception is thrown, and an error message is returned 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, which includes:
$fault<reason>
to the value of the body context variable <Notes>
field.Complete the following steps to design and configure the proxy service and the associated resources in AquaLogic Service Bus to resolve this user case scenario:
Ensure that AquaLogic Service Bus is running in the domain you created for the tutorial and that you have completed the steps described in Tutorial 1. Routing a Loan Application.
For this tutorial, you use the project folder, MortgageBroker
, and the directory structure you created in Tutorial 1. Routing a Loan Application to hold the project artifacts.
In this step, you will create the proxy service, LoanGateway3. You will use the existing normalLoan
service WSDL resource as the basis on which to validate the content of the message. This WSDL resource was created in Tutorial 1. Routing a Loan Application in the section Create the normalLoan Service WSDL Resource. If the loan application is valid, that is, it meets the expected criteria, it is routed to the existing normalLoan
business service. This business service was created in Tutorial 1. Routing a Loan Application in the section To Create the Normal Loan Business Service.
In this step, you create a proxy service. The proxy service is used to route the loan application to the appropriate business service. Base this proxy service on the proxy service you previously created in Tutorial 1.
To create a new proxy service, follow the steps described in To Create the Proxy Service, but for this instance use the proxy service name and the Endpoint URI described in the following table.
Table 5-2 Proxy Service Configuration Settings
Review the configuration settings prior to registering the proxy service.
When you complete this step, the MortgageBroker/ProxyService
folder contains the proxy services you created in this tutorial and in Tutorial 1. Routing a Loan Application:
The proxy service is implemented in AquaLogic Service Bus as a message flow, which includes request and response pipelines. AquaLogic Service Bus Message Flows define the implementation of proxy services. Message flows can include zero or more pipeline pairs: request and response pipelines for the proxy service (or for the operations on the service) and error handler pipelines that can be defined for stages, pipelines, and proxy services. Pipelines can include one or more stages, which in turn include actions. To configure the behavior of the LoanGateway3
proxy service, you will complete the following for the message flow:
The PipelinePairNode1
is created and placed in the message flow. Request and response pipelines are displayed for this node as shown in the following figure.
You must now configure the request actions for the proxy service.
The screen should appear as shown in the following figure.
Figure 5-3 Add Stage to Request Pipeline
Add an Action
link and select Validate from the drop-down list. The Validate action is added to the stage.
link to edit the XPath expression. The XPath Expression Editor page is displayed.loanRequest
element, drag and drop it in the XQuery Expression text box. The XQuery expression is written 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 loanRequest
element in the Variable Structures pane. The expression is displayed in the Property Inspector palette. Place the cursor in the XQuery expression text box and click Copy Property. The expression is copied to the text box. You can also copy the expression in the palette and paste it into the XQuery Expression text box.
It is good practice to do this before you submit the expression. The expression is validated for syntax. If there are errors in the expression, they are displayed directly above the Validate button. In this case the expression is valid.
You are returned to the Edit Stage Configuration page. <XPath>
is replaced by the XQuery expression.
The validate action should appear as shown in the following figure.
Figure 5-4 Configure Action for Message Validation
Note: Validation of a message should happen as early as possible in a message flow. This prevents unnecessary processing of the message in a case where the content of the message may be invalid. If an exception is raised, further processing is stopped and a response is immediately returned to the client.
Messages can be validated at the route node or using a separate Validate action (as in this case). Creating a Validation stage make the processing of the message more modular and logically breaks out the actions in the message flow. In a case where multiple validations may be preformed on a message, it allows for logical expansion of the validate action.
Add a Replace action to the stage and configure this action to replace the Notes
element value with the fault
context variable reason
text. This results in the fault
description being returned to the client.
Figure 5-5 Edit Name and Description of Stage
Figure 5-6 Edit ErrorHandler page
Notes
element of $body
, drag and drop it on the XPath Expression text box. The following XPath expression is written 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 Notes
element in the Variable Structures pane. The expression is displayed in the Property Inspector palette. Place the cursor in the XPath expression text box and click Copy Property. The expression is copied to the text box. You can also copy the expression in the palette and paste it into the XPath Expression text box.
The replace action should appear as shown in the following figure.
Figure 5-7 Add Error Handler Using Replace Action
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.
Expression>
link. The XQuery Expression Editor page is displayed.body - processLoanApp
from the Select Structure drop-down list.$body
element and drag and drop it on the XQuery Expression 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. The expression is displayed in the Property Inspector palette. Place the cursor in the XQuery expression text box and click Copy Property. The expression is copied to the text box. You can also copy the expression in the palette and paste it into the XQuery Expression text box.
errorCode
and drag and drop it on the XPath Expression 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. Place the cursor in the XPath expression text box and click Copy Property. The expression is copied to the text box. You can also copy the expression in the palette and paste it into the XPath Expression text box.
Note: To Add an action on a page, click the Action preceding the placement of the new action and select the Action to add from there. Actions are added in sequence.
The report action should appear as shown in the following figure.
Now, the Edit Stage Configuration page should appear as shown in the following figure.
Figure 5-10 Request Actions for LoanGateway3 Proxy Service
Add a Route Node to the Pipeline pair, then configure the Route Node to route to the normalLoan
business service.
Service
link to define the service to which you want to route the messages. The Select Service page is displayed. 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 screen should appears as shown in the following figure.
Figure 5-11 Configure Message Flow of LoanGateway3 Proxy Service
You can view the map of the message flow of the proxy service as shown in the following figure.
Figure 5-12 Map of Message Flow of the LoanGateway3 Proxy Service
Now that you have configured BEA AquaLogic Service Bus to work with the client and the target business services, you can test the configuration. Testing is done on the command line by changing the value of the Loan duration (in years) field in the build.xml
file and then running ant
. The behavior for the proxy service in this scenario depends on the correct value being entered for the loan duration. If a non-integer value is entered for the loan, then a fault is triggered and an error message results:
NormalLoanApprovalService
business service.This section describes how to test the proxy service for both cases. The message returned in the command window after running a test indicates whether a validation exception results or whether the message was routed to the appropriate business service.
Note: Run the tests in this section multiple times (at least five times) to generate data to enable you to explore the reporting and monitoring features described in Step 7: Using Reporting and Monitoring.
This section includes the following test scenarios:
To run this test correctly, ensure that WebLogic Server is started in the BEA AquaLogic Service Bus 2.1 (ServiceBusTutorial) domain.
BEA_HOME
\weblogic91\samples\servicebus\examples\src\
setEnv.cmd
Note: If you are testing the configuration on a UNIX system, run the setEnv.sh
script at your command line prompt.
BEA_HOME
\weblogic91\samples\servicebus\examples\src\examples\webservices\jws_basic\normal
build.xml
file run target:
<arg line="http://$...
<arg line="http://${wls.hostname}:${wls.port}/loan/gateway3 steve 555 2500 20.5 4.9 notes" />
This changes the URI to that of the proxy service running in the tutorial domain, and specifies a value of 20.5
(a non-integer value) for the loan duration.
The remainder of the input parameters specified on the arg line
are described in the following table.
ant
run
[java] Loan Application Response: ALSB Validate action failed validation
[java] Rate: 4.9
BUILD SUCCESSFUL
The response message indicates that a validation exception occurred as the value entered in the loan duration field was a non-integer value.
build.xml
file in the following directory:
BEA_HOME
\weblogic91\samples\servicebus\examples\src\examples\webservices\jws_basic\normal
Note: In this case (to test the NormalLoanApprovalService
business service), enter a value of 20 for the loan duration in the build.xml
file (see Table 5-3), then save the changes.
ant run
The response message indicates that the NormalLoan
business service processed the request because the loan duration requested was 20, an integer value.
Now that you have tested the proxy service you can explore the reporting and monitoring features of the AquaLogic Service Bus Console.
Note: You must have run the tests in Step 6: Test Your Loan Application Routing Configuration multiple times (at least five times) to generate data to enable you to explore the reporting and monitoring features.
AquaLogic Service Bus includes a JMS Reporting Provider for message reporting. The Reporting module in the AquaLogic Service Bus Console displays the information captured from this reporting provider. If you do not wish to use the out-of-the-box reporting provider, you can create your own reporting provider using the Reporting Service Provider Interface (SPI).
Reporting automatically happens in the AquaLogic Service Bus Console. Reporting features are available from the Dashboard. Information is presented in a drill-down format. The more you explore the links presented, the more information is made available to you.
BEA AquaLogic Service Bus provides the capability to monitor and collect run-time information for both systems operations and business auditing purposes. AquaLogic 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.