|Oracle® BPEL Process Manager Developer's Guide
Part Number B28981-03
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.
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 syncMaxWaitTime
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 defines the following characteristics of the conversion between a BPEL process and the loan application approver Web service:
The role (operation) played by each
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>
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.
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
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
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.
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.
Figure 4-1 Diagram of QuoteConsumer.bpel
The following actions take place:
The receiveInput receive activity receives input from the user (client), as defined in the
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>