Oracle® BPEL Process Manager Developer's Guide 10g (10.1.3.1.0) Part Number B28981-03 |
|
|
View PDF |
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 are used as examples in this chapter.SOA_Oracle_Home
\bpel\samples\tutorials\104.SyncQuoteConsumer\bpel\QuoteConsumer.bpel
SOA_Oracle_Home
\bpel\samples\tutorials\104.SyncQuoteConsumer\bpel\bpel.xml
SOA_Oracle_Home
\bpel\samples\tutorials\104.SyncQuoteConsumer\bpel\QuoteConsumer.wsdl
SOA_Oracle_Home
\bpel\samples\utils\104.StockQuoteService\bpel\StockQuoteService.wsdl
A synchronous callback requires the following 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 45
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.
See Also:
Oracle Application Server Performance Guide for additional details about syncMaxWaitTimeThis 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.
To access this registry when creating a partner link, you must first create a connection to the UDDI registry:
Right-click UDDI Registry in the Connection Navigator of Oracle JDeveloper.
Select New UDDI Registry Connection.
Follow the wizard steps to create a connection.
When creating a partner link, you can also select Web services on remote servers. To specify the remote location, edit
SOA_Oracle_Home\bpel\system\services\install\config\inspection.wsil
The Web service is then accessible from Oracle JDeveloper. Click the Service Explorer icon when creating a partner link on the Create Partner Link window. This displays the Service Explorer window, which enables you to select the remote Web service.
See Also:
"PartnerLink"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>
See Also:
"Invoke Activity"This section examines a synchronous callback operation using the QuoteConsumer.bpel
file. For a more step-by-step approach, see http://www.oracle.com/technology/bpel
and download the files under Training Material.
shows the diagram of the QuoteConsumer.bpel
file, which defines a simple application with five activities.
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 invokeStockQuoteService activity 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 performs the synchronous callback:
<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>