BPEL BluePrint 1

Synchronous Web Service Interactions Using BPEL

Kiran Bhumana, Ryan Kennedy, Shauna Pickett-Gordon

Problem Description

The Business Process Execution Language (BPEL) provides a simple and efficient way of bringing multiple web services together into new composite services that represent business processes (also called BPEL processes).

Before attempting to model real-world business processes using BPEL, we need to understand the steps involved in describing business processes in this new language, and how to consume and provide for synchronous web service operations from within a BPEL process.

Solution

Synchronous operations are appropriate in business processes that require an immediate response to a request. Execution proceeds on the consumer side only after the response arrives and is consumed.

Two aspects are demonstrated in this solution:

A BPEL process that provisions one or more synchronous operations
A BPEL process that consumes one or more synchronous operations provisioned by one or more partner web services

Provisioning a Synchronous Operation

Provisioning a synchronous operation (also called a request-response, or in-out, operation) involves receiving a message and replying with a response message as defined by the web service. BPEL defines the following constructs to enable the provisioning of a synchronous operation:

A receive activity or an onMessage activity
A reply activity

A given pair of activities--consisting of a receive (or onMessage) and a reply--together provision the request-response for a single synchronous operation.

Consuming a Synchronous Operation

Consuming an in-out operation involves sending a message and expecting a response message as defined by the web service. BPEL defines an invoke activity that enables the consumption of operations defined by partner web services. A BPEL process commonly invokes multiple web services as part of its orchestration, and then makes use of the response messages.

With these BPEL constructs and those explained in the second BPEL BluePrint, you can define complex business processes that mirror relationships and dependencies between real-world business interactions.

Design Details

You'll need to consider certain design details when you use the Business Process Execution Language (BPEL) to describe the following:

An executable business process that provisions a synchronous operation
An executable business process that consumes a synchronous operation on a separate web service

Provisioning a synchronous operation involves receiving a message and replying with a message defined by the web service. Consuming a synchronous operation involves sending a message and expecting a response message defined by the web service.

When designing a business process that incorporates synchronous web service interactions, the following constructs are needed.

partnerLinks representing partner web services
variables that store data exchanged between web services
An invoke activity to consume a service
A receive-reply activity pair to provide a service
Input and output data mapping to achieve some meaningful business logic

The following solution shows how to create and use the BPEL artifacts to both provide for and consume synchronous web service operations. First, an external client consumes a single synchronous operation provisioned by a BPEL process. Then, this BPEL process consumes a synchronous operation provisioned by another BPEL process. The solution is illustrated next.

Figure 1: Synchronous Web Service Interaction

Although this example illustrates a business process consisting of multiple synchronous interactions, a single BPEL process can provision and consume both synchronous and asynchronous operations. Refer to BluePrint 2, Asynchronous Web Service Interactions Using BPEL, for an example of how to combine synchronous and asynchronous interactions in a BPEL process.

Business Logic of the Services

Two web services are involved here: a purchase order service, POService, which is consumed by an external client through SOAP over HTTP; and an inventory check service, InventoryService, consumed by the BPEL process that provisions the purchase order service. Both POService and InventoryService are implemented as BPEL services.

When the purchase order service provider receives the client request, the following events happen:

The purchase order service provider:
1. Assigns the price and the current date of the request.
2. Invokes the inventory service to check inventory status.
The inventory service provider's business logic checks the availability of an item.
If the incoming purchase order's orderDescription value starts with OrderVal, then the order's status is available in the inventory.
Based on the result from the inventory service, the purchase order service provider responds with one of the following:
- The fulfilled purchase order
- A fault stating that the order cannot be completed

Define the WSDL

When you define a business process, you are creating a new web service that comprises existing web services. The WSDL for this new web service defines the relationships between this and other web services.

<partnerLinkType>

A partnerLinkType specifies the relationship between two services by defining the role that each service implements. Each role specifies exactly one WSDL portType type that must be implemented by the service that implements that role.

In this example, the PurchaseOrder WSDL defines a partnerLinkType with a role purchaseService. The purchaseService role refers to the sendPurchaseOrder WSDL operation through a portType called purchaseOrderPT.

    <plink:partnerLinkType name="purchasingLT">
        <plink:role name="purchaseService"
                    portType="tns:purchaseOrderPT"></plink:role>
    </plink:partnerLinkType>

The sendPurchaseOrder operation defines an input to be sent to the provider, and expects either a reply or a fault. In a web service in-out operation, an input message is mandatory. You cannot define this kind of operation with only a response or a fault. The invoker may send an input message and expect either a response message or fault. Synchronous web service calls are similar to method calls or subroutines in most programming languages.

    <portType name="purchaseOrderPT">
        <operation name="sendPurchaseOrder">
            <input name="sendPurchaseOrderRequest" message="tns:POMessage"></input>
            <output name="sendPurchaseOrderReply" message="tns:POMessage"></output>
            <fault name="cannotCompleteOrder"
                   message="tns:orderFaultType"></fault>
        </operation>
    </portType>

The InventoryService WSDL defines a partnerLinkType with the role inventoryService. This role refers to the inventoryService operation through the portType called inventoryPortType.

    <plink:partnerLinkType name="inventoryRequestingLT">
        <plink:role name="inventoryService"
                    portType="tns:inventoryPortType"></plink:role>
    </plink:partnerLinkType>

The inventoryService operation expects a purchaseOrder message, and replies with either inventoryStatus or inventoryFaultType.

     <portType name="inventoryPortType">
         <operation name="inventoryService">
             <input name="purchaseOrder"
                   message="tns:POMessage"></input>
             <output name="inventoryStatus"
                    message="tns:InventoryMessage"></output>
             <fault name="inventoryFaultType"
                   message="tns:inventoryFault"></fault>
         </operation>
     </portType>

NOTE: If the WSDL file of an existing web service does not contain a definition for partnerLinkType, you can create a wrapper WSDL file to import the original WSDL file, and then add the partnerLinkType definition in the wrapper. Afterwards, you can refer to the wrapper from your BPEL process.

Define the BPEL Process

<partnerLink>

The partnerLink elements specify the partners and clients with which a BPEL process interacts. Each partnerLink corresponds to a specific partnerLinkType as defined in the WSDL.

A partnerLink element must also contain one or two roles:

myRole. This specifies the role of the BPEL process. If you define only myRole for partnerLink, you enable any partner or client to interact with the BPEL process, without requiring anything of the other partner or client.
partnerRole. This specifies the role of the partner or client. If you define only partnerRole for partnerLink, you enable interactions with a partner or client, without imposing requirements on its caller.

The POService BPEL process defines a partnerLink called POServicePLink to indicate its role as a provider of the operation sendPurchaseOrder.

        <partnerLink name="POServicePLink"
                     partnerLinkType="pos:purchasingLT"
                     myRole="purchaseService"/>

Since POService also consumes the InventoryService, a partnerLink called requestInventoryPLink is also defined.

        <partnerLink name="requestInventoryPLink"
                     partnerLinkType="invs:inventoryRequestingLT"
                     partnerRole="inventoryService"/>

<variables>

BPEL defines variables that the business process uses as part of its logic. Next are some variables defined by the POService BPEL process.

    <variables>
        <variable name="purchaseOrderRequest"
                  messageType="pos:POMessage"></variable>
        <variable name="purchaseOrderReply"
                  messageType="pos:POMessage"></variable>
        <variable name="inventoryServiceRequest"
                  messageType="invs:POMessage"></variable>
        <variable name="inventoryServiceReply"
                  messageType="invs:InventoryMessage"></variable>
    </variables>

<receive> and <reply>

In a receive-reply pair, only one outstanding reply activity can correspond to an executed receive. This means that, at most, one reply is executed for a given receive. In this example, one receive is matched by two reply activities: one corresponds to the expected valid response, and the other corresponds to a fault defined on the operation.

In the static BPEL model, there are two matching reply activities for a single receive. However, at runtime, only one reply is executed, because the reply activities are on mutually exclusive branches of execution. Therefore, the execution doesn't result in a missingRequest standard fault, as defined in the BPEL specification.

    <receive name="sendPurchaseOrder"
                 partnerLink="POServicePLink"
                 portType="pos:purchaseOrderPT"
                 operation="sendPurchaseOrder"
                 variable="purchaseOrderRequest"
                 createInstance="yes">
    </receive>
 
    <reply name="sendPurchaseOrder.Reply"
                 partnerLink="POServicePLink"
                 portType="pos:purchaseOrderPT"
                 operation="sendPurchaseOrder"
                 variable="purchaseOrderRequest">
    </reply>

<invoke>

An invoke activity has the effect of consuming a web service.

    <invoke name="inventoryService"
                 partnerLink="requestInventoryPLink"
                 portType="invs:inventoryPortType"
                 operation="inventoryService"
                 inputVariable="inventoryServiceRequest"
                 outputVariable="inventoryServiceReply">
    </invoke>

A visual form of the POService BPEL process is shown next.

Figure 2: The POService BPEL Process

Note: While the WS-BPEL specification itself does not include a graphical notation, many tools provide visual diagramming environments that generate BPEL source code. The BPEL Designer available in the NetBeans Enterprise Pack 5.5 Beta IDE provides a visual editor for diagramming business processes, as seen above.

The InventoryService BPEL Process

The BPEL process InventoryService defines a partnerLink called inventoryServicePLink, indicating its role as the service provider.

       <partnerLink name="inventoryServicePLink"
                     partnerLinkType="invs:inventoryRequestingLT"
                     myRole="inventoryService"/>

Here are some of the variables defined by the InventoryService process.

       <variables>
            <variable name="purchaseOrder"
                  messageType="invs:POMessage"></variable>
            <variable name="inventoryStatus"
                  messageType="invs:InventoryMessage"></variable>
       </variables>

The InventoryService process defines a matching receive and reply for the operation, as follows.

       <receive name="inventoryService"
                 partnerLink="inventoryServicePLink"
                 portType="invs:inventoryPortType"
                 operation="inventoryService"
                 variable="purchaseOrder"
                 createInstance="yes">
        </receive>

        <reply name="inventoryService.Reply"
               partnerLink="inventoryServicePLink"
               portType="invs:inventoryPortType"
               operation="inventoryService"
               variable="inventoryStatus">
        </reply>

A visual form of the InventoryService BPEL process is shown next.

Figure 3: The InventoryService BPEL Process

Refer to the BPEL process code for further details of the business logic implementation.

Input Data XML

The following input XML instance gives a valid response.

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns="http://manufacturing.org/xsd/purchase" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/ http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <sendPurchaseOrder>
      <purchaseOrder>
        <purchaseOrder xmlns="http://manufacturing.org/xsd/purchase">
          <orderId>012341</orderId>
      	  <customerId>9876</customerId>
          <orderDescription>OrderVal_Any_Description</orderDescription>
          <price></price>
        </purchaseOrder>
      </purchaseOrder>
    </sendPurchaseOrder>
  </soapenv:Body>
</soapenv:Envelope>

References

Browse the source code for this BluePrint, including the BPEL process files and WSDL files.
See the BPEL BluePrint sample projects included in the NetBeans Enterprise Pack 5.5 Beta IDE.

© Sun Microsystems 2006. All of the material in The Java BluePrints Solutions Catalog is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.