|Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite
11g Release 1 (11.1.1)
Part Number E10224-01
This chapter describes how to invoke a synchronous web service from a BPEL process. This chapter demonstrates how to set up the components necessary to perform a synchronous invocation. This chapter also examines how these components are coded.
This chapter includes the following sections:
For a simple Hello World sample (
bpel-101-HelloWorld) that takes an input string, adds a prefix of
"Hello " to the string, and returns it, visit the following URL:
Synchronous web services provide an immediate response to an invocation. BPEL can connect to synchronous web services through a partner link, send data, and then receive the reply in the same synchronous invocation.
A synchronous invocation requires the following components:
Defines the location and the role of the web services with which the BPEL process service component connects to perform tasks, and the variables used to carry information between the web service and the BPEL process service component. A partner link is required for each web service that the BPEL process service component calls. You can create partner links in either of two ways:
In the SOA Composite Editor, when you drag a Web Service from the Component Palette into the Exposed Services or External References swimlane.
In the Oracle BPEL Designer, when you drag a Partner Link (Web Service/Adapter) from the Component Palette into the Partner Links swimlane. This method is described in this chapter.
Opens a port in the BPEL process service component to send and receive data. It uses this port to retrieve information verifying that the customer has acceptable credit using the CreditCardAuthorizationService. For synchronous callbacks, only one port is needed for both the send and receive functions
Note:You can specify timeout values with the attribute
/config/soa-infra/configuration/bpel-config.xmlfile or with the System MBean Browser setting of
oracle.as.soainfra.config:type=BPELConfig,name=bpelin Oracle Enterprise Manager Fusion Middleware Control Console. If the BPEL process service component does not receive a reply within the specified time, then the activity fails.
This section examines a synchronous invocation operation using the
OrderProcessor.bpel file in the WebLogic Fusion Order Demo application as an example. For a more step-by-step approach, see Oracle Fusion Middleware Tutorial for Running and Building an Application with Oracle SOA Suite.
To invoke a synchronous web service:
In the Component Palette in Oracle BPEL Designer, drag the necessary partner link, invoke activity, and assign activities into the designer.
Edit their dialogs. Procedures are described in Oracle Fusion Middleware Tutorial for Running and Building an Application with Oracle SOA Suite.
shows the diagram for the Scope_AuthorizeCreditCard scope activity of the OrderProcessor.bpel file, which defines a simple set of actions.
Figure 8-1 Diagram of OrderProcessor.bpel
The following actions take place:
The Assign_CreditCheckInput assign activity packages the data from the client. The assign activity provides a method for copying the contents of one variable to another. In this case, it takes the credit card type, credit card number, and purchase amount and assigns them to the input variable for the CreditAuthorizationService service.
The InvokeCheckCreditCard activity calls the CreditCardAuthorization service. shows the CreditCardAuthorizationService web service, which is defined as a partner link.
Figure 8-2 CreditCardAuthorizationService Partner Link
shows the InvokeCheckCreditCard invoke activity.
Figure 8-3 InvokeCheckCreditCard Invoke Activity
The Switch_EvaluateCCResult switch activity checks the results of the credit card validation. For information about switch activities, see Section 11.2, "Creating a Switch Activity to Define Conditional Branching."
When you create a partner link and invoke activity, the necessary BPEL code for invoking a synchronous web service is added to the appropriate BPEL and Web Services Description Language (WSDL) files.
OrderProcessor.bpel code, the partner link defines the link name and type, and the role of the BPEL process service component in interacting with the partner service.
From the BPEL source code, the
CreditCardAuthorizationService partner link definition is shown in Example 8-1:
Example 8-1 Partner Link Definition
<partnerLink name="CreditCardAuthorizationService" partnerRole="CreditAuthorizationPort" partnerLinkType="ns2:CreditCardAuthorizationService"/>
Variable definitions that are accessible locally in the
Scope_AuthorizeCreditCard scope are shown in Example 8-2. The types for these variables are defined in the WSDL for the process itself.
Example 8-2 Variable Definition
<variable name="lCreditCardInput" messageType="ns2:CreditAuthorizationRequestMessage"/> <variable name="lCreditCardOutput" messageType="ns2:CreditAuthorizationResponseMessage"/>
The WSDL file defines the interface to your BPEL process service component: the messages that it accepts and returns, the operations that are supported, and other parameters.
The web service's
.wsdl file contains two sections that enable the web service to work with BPEL process service components:
Defines the following characteristics of the conversion between a BPEL process service component and the credit card authorization web service:
The role (operation) played by each
portType provided by each for receiving messages within the conversation
A collection of related operations implemented by a participant in a conversation. A port type defines which information is passed back and forth, the form of that information, and so on. A synchronous invocation requires only one port type that both initiates the synchronous process and calls back the client with the response. An asynchronous callback (one in which the reply is not immediate) requires two port types, one to send the request, and another to receive the reply when it arrives.
In this example, the
CreditAuthorizationPort receives the credit card type, credit card number, and purchase amount, and returns the status results.
Example 8-3 provides an example of
invoke activity includes the
lCreditCardInput local input variable. The credit card authorization web service uses the
lCreditCardInput input variable. This variable contains the customer's credit card type, credit card number, and purchase amount. The
lCreditCardOutput variable returns status results from the
CreditAuthorizationService service. Example 8-4 provides an example.
The BPEL code shown in Example 8-5 performs the synchronous invocation:
Example 8-5 Synchronous Invocation
<assign name="Assign_CreditCheckInput"> <copy> <from variable="gOrderInfoVariable" query="/ns4:orderInfoVOSDO/ns4:OrderTotal"/> <to variable="lCreditCardInput" part="Authorization" query="/ns8:AuthInformation/ns8:PurchaseAmount"/> </copy> <copy> <from variable="gOrderInfoVariable" query="/ns4:orderInfoVOSDO/ns4:CardTypeCode"/> <to variable="lCreditCardInput" part="Authorization" query="/ns8:AuthInformation/ns8:CCType"/> </copy> <copy> <from variable="gOrderInfoVariable" query="/ns4:orderInfoVOSDO/ns4:AccountNumber"/> <to variable="lCreditCardInput" part="Authorization" query="/ns8:AuthInformation/ns8:CCNumber"/> </copy> </assign> <invoke name="InvokeCheckCreditCard" inputVariable="lCreditCardInput" outputVariable="lCreditCardOutput" partnerLink="CreditCardAuthorizationService" portType="ns2:CreditAuthorizationPort" operation="AuthorizeCredit"/>
You can expose a synchronous interface in the front end while using an asynchronous callback in the back end to simulate a synchronous reply. This is the default behavior in BPEL processes with the automatic setting of the
configuration.transaction property to
requiresNew in the
composite.xml file. Example 8-6 provides details.
Example 8-6 configuration.transaction Property
<component name="BPELProcess1"> @ <implementation.bpel src="BPELProcess1.bpel"/> @ <property name="configuration.transaction" type="xs:string" @ many="false">requiresNew</property> @ </component>
RequiresNew is the recommended value. If you want to participate in the client's transaction, you must set the
configuration.transaction property to