|
Oracle® BPEL Process Manager Developer's Guide
10g Release 2 (10.1.2) B14448-02 |
|
 Previous |
 Next |
|
Oracle® BPEL Process Manager Developer's Guide
10g Release 2 (10.1.2) B14448-02 |
|
|
Previous |
Next |
Synchronous Web services provide an immediate response to a query. BPEL can connect to synchronous Web services through a partner link, send data, and then receive the reply using a synchronous callback.
This chapter contains the following topics:
Using synchronous Web services is demonstrated in 104.SyncQuoteConsumer. This sample shows a BPEL process sending a stock code to a Web service and receiving a stock quote in return. It examines how synchronous functionality is defined in the stock quote Web service's CreditRatingService.wsdl file (the Web service to be called) and the client's QuoteConsumer.bpel file and bpel.xml deployment description file.
This chapter demonstrates how to establish a partner link and set up a synchronous callback. It discusses the components necessary to perform a synchronous callback, examines how these components are coded, and shows how to set up a synchronous callback.
|
See Also: The following files used as examples in this chapter:If you are using Eclipse BPEL Designer:
If you are using JDeveloper BPEL Designer:
|
A synchronous callback requires the following two key components:
Partner link: Defines the location and the role of the Web services that the BPEL process connects to in order to perform tasks, as well as the variables used to carry information between the Web service and the BPEL process. A partner link is required for each Web service that the BPEL process calls.
Invoke activity: Opens a port in the BPEL process to send and receive data. It uses this port to submit the required data and receive the response. In the credit rating service example, the invoke activity submits the stock code entered by the customer to the stock quote service and receives a stock quote in return. For synchronous callbacks, only one port is needed for both the send and receive functions.
Each domain has the attribute syncMaxWaitTime. This attribute has a default of 60 seconds, but can be reconfigured by the domain administrator. If the BPEL process does not receive a reply within the specified time, then the activity fails.
This section covers the following topics:
In the BPEL code, the partner link defines the link name and type, and the role of the BPEL process in interacting with the partner service.
From the BPEL source code, the StockQuoteService partner link definition is as follows:
<partnerLinks>
<!--
The 'client' role represents the requester of this service. It is
used for callback. The location and correlation information associated
with the client role are automatically set using WS-Addressing.
-->
<partnerLink name="client" partnerLinkType="samples:QuoteConsumer"
myRole="QuoteConsumerProvider" partnerRole="QuoteConsumerRequester"/>
<partnerLink name="StockQuoteService"partnerLinkType="services:StockQuoteService"
partnerRole="StockQuoteServiceProvider"/>
</partnerLinks>
Following the partner link are global variable definitions that are accessible throughout the BPEL process. The types for these variables are defined in the WSDL for the process itself.
<variables>
<!-- Reference to the message passed as input during initiation -->
<variable name="input" messageType="tns:QuoteConsumerRequestMessage"/>
<!-- Reference to the message that will be sent back to the
requestor during callback
-->
<variable name="output" messageType="tns:QuoteConsumerResultMessage"/>
<variable name="request" messageType="services:StockQuoteServiceRequest"/>
<variable name="response" messageType="services:StockQuoteServiceResponse"/>
</variables>
The WSDL file defines the interface to your BPEL process—the messages that it accepts and returns, operations that are supported, and other parameters.
The Web service's QuoteConsumer.wsdl file contains two sections that enable it to work with BPEL processes:
partnerLinkType Section of the QuoteConsumer.wsdl File
The partnerLinkType section of the QuoteConsumer.wsdl file defines the following characteristics of the conversion between a BPEL process and the loan application approver Web service:
The role (operation) played by each
The portType provided by each for receiving messages within the context of the conversation
<!--
PartnerLinkType definition
-->
<!-- the QuoteConsumer partnerLinkType binds the service and
requestor portType into an asynchronous conversation.
-->
<plnk:partnerLinkType name="QuoteConsumer">
<plnk:role name="QuoteConsumerProvider">
<plnk:portType name="tns:QuoteConsumer"/>
</plnk:role>
<plnk:role name="QuoteConsumerRequester">
<plnk:portType name="tns:QuoteConsumerCallback"/>
</plnk:role>
</plnk:partnerLinkType>
portType Section of the QuoteConsumer.wsdl File
A port type is a collection of related operations implemented by a participant in a conversation. A port type defines what information is passed back and forth, the form of that information, and so forth. A synchronous callback requires only one port type that both sends a request and receives the response, while an asynchronous callback (one where the reply is not immediate) requires two port types, one to send the request, and another to receive the reply when it arrives.
View the portType section of the QuoteConsumer.wsdl file. This is the stock quote Web service to which the client submits the stock code that the customer has entered.
<!--
PortType definition
-->
<!-- portType implemented by the QuoteConsumer BPEL process -->
<portType name="QuoteConsumer">
<operation name="initiate">
<input message="tns:QuoteConsumerRequestMessage"/>
</operation>
</portType>
<!-- portType implemented by the requester of QuoteConsumer BPEL process
for asynchronous callback purposes
-->
<portType name="QuoteConsumerCallback">
<operation name="onResult">
<input message="tns:QuoteConsumerResultMessage"/>
</operation>
</portType>
Synchronous services have one port type. The port initiates the synchronous process and calls back the client with the response. In this example, the portType CreditRatingService receives the stock code and returns the stock quote.
A Universal Description, Discovery, and Integration (UDDI) browser is provided for looking up services when creating a partner link. Web Services Inspection Language (WSIL) and UDDI assist in the publishing and discovery of services.
UDDI is a Web-based distributed directory that enables businesses to list themselves on the Internet and discover each other, similar to a traditional phone book's yellow and white pages. The specification provides a high level of functionality through the sample object access protocol (SOAP) by specifically requiring an infrastructure to be deployed.
WSIL approaches service discovery in a decentralized fashion, where service description information can be distributed to any location using a simple extensible XML document format. Unlike UDDI, it is not concerned with business entity information, nor does it specify a particular service description format. WSIL works under the assumption that you are already familiar with the service provider, and relies on other service description mechanisms such as WSDL.
When creating a partner link, you can also select Web services on remote servers. Edit the Oracle_Home\integration\jdev\jdev\lib\ext\inspection.wsil file to specify the remote location.
The Web service is then accessible from JDeveloper BPEL Designer. Click the WSIL Browser icon when creating a partner link on the Create Partner Link window. This displays the WSDL Chooser window, which enables you to select the remote Web service.
The invoke activity includes the request global input variable defined in the variables section. The credit rating Web service uses this request global input variable. This variable contains the customer's social security number. The response variable contains the credit rating returned by the credit rating service.
<sequence>
<!-- Receive input from requestor.
Note: This maps to operation defined in QuoteConsumer.wsdl
-->
<receive name="receiveInput" partnerLink="client" portType="samples:QuoteConsumer"
operation="initiate" variable="input" createInstance="yes"/>
<assign>
<copy>
<from variable="input" part="payload" query="/tns:symbol"/>
<to variable="request" part="symbol" query="/symbol"/>
</copy>
</assign>
<!-- Generate content of output message based on the content of the
input message.
-->
<invoke name="invokeStockQuoteService" partnerLink="StockQuoteService"/>
<assign>
<copy>
<from variable="response" part="result" query="/result"/>
<to variable="output" part="payload" query="/tns:result"/>
</copy>
</assign>
<!-- Asynchronous callback to the requester.
Note: the callback location and correlation id is transparently handled
using WS-addressing.
-->
<invoke name="replyOutput" partnerLink="client"
portType="samples:QuoteConsumerCallback" operation="onResult"
inputVariable="output"/>
</sequence>
This section examines the QuoteConsumer.bpel file so that you can explore the concepts involved with a synchronous callback operation. You can import the project file at this location to examine the application. For a more step-by-step approach, see http://www.oracle.com/technology/bpel and download the files under BPEL Training Materials.
provides an overview of the QuoteConsumer.bpel file in Eclipse BPEL Designer, which defines a simple application with five activities.
Figure 5-1 Overview of QuoteConsumer.bpel
The following actions take place:
The receiveInput receive activity receives input from the user (client), as defined in the QuoteConsuter.wsdl file.
The first assign activity packages the data from the client so that it can be accepted by the invokeStockQuote service.
The invokeStockQuote service sends the repackaged data to the StockQuoteService service and receives a response.
A second assign activity repackages this response into a replyOutput activity so that it can be accepted by the client application.
The replyOutput activity sends the repackaged response back to the client.
The following BPEL code that performs the synchronous callback is on lines 61–91:
<assign>
<copy>
<from variable="input" part="payload" query="/tns:symbol"/>
<to variable="request" part="symbol" query="/symbol"/>
</copy>
</assign>
<invoke name="invokeStockQuoteService" partnerLink="StockQuoteService"
portType="services:StockQuoteService" operation="process"
inputVariable="request" outputVariable="response"/>
<!-- Generate content of output message based on the content of the
input message.
-->
<assign>
<copy>
<from variable="response" part="result" query="/result"/>
<to variable="output" part="payload" query="/tns:result"/>
</copy>
</assign>
