Handling business faults from an asynchronous BPEL process

The faults that occur either in a synchronous or asynchronous BPEL process are treated the same way inside the BPEL process. The difference, however, exists in the way the client is notified about the fault in the BPEL process. We said earlier that the client is not blocked when calling an asynchronous BPEL process. Since the communication is closed between the BPEL process and client after initiation of BPEL, we need to find a way to notify the client that something went wrong in the BPEL process. This recipe will show you how to handle the faults from the asynchronous BPEL processes.

Getting ready


We modified the asynchronous BPEL process from the Calling an asynchronous BPEL process recipe. We added the If activity, which checks the content of the input parameter of the BPEL process. If the input parameter contains FAULT text, then the BPEL process finishes immediately; otherwise, the BPEL process waits for some time and sends success to the client. The modified asynchronous BPEL process is shown in the following screenshot:

We notify the two reply activities. The callbackClient invoke activity is used in case the asynchronous BPEL process finishes successfully. We add the new invoke activity named returnFault for cases when we need to report the fault back to the client. We model the asynchronous BPEL process with the additional callback operation because the communication between the BPEL process and client is closed immediately after the client initiates the BPEL process, and there is no way the BPEL process can notify the client about the faults. We start by defining the fault message structure in the HelloWorldAsyncProcess.xsd schema as follows:

<element name="fault">
  <complexType>
    <sequence>
      <element name="msg" type="string"/>
    </sequence>
  </complexType>
</element>

We define the fault message structure the same way as we did with the synchronous BPEL process. We also modify the WSDL description of the asynchronous BPEL process (HelloWorldAsyncProcess.wsdl). Initially, we define the message for the fault as follows:

<wsdl:message name = "ProcessFaultMessage">
  <wsdl:part name = "message" element = "client:fault"/>
</wsdl:message>

We define a SOAP message containing the fault message later inside the <wsdl:operation> element of <wsdl:binding element> as follows:

<wsdl:binding name = "HelloWorldAsyncProcessCallbackBinding" type = "client:HelloWorldAsyncProcessCallback">
  <soap:binding transport = "http://schemas.xmlsoap.org/soap/http"/>
  <wsdl:operation name = "processFault">
    <soap:operation style = "document" soapAction = "processFault"/>
    <wsdl:input>
      <soap:body use = "literal" namespace = "http://xmlns.oracle.com/HelloWorldAsync/HelloWordlAsync/HelloWorldAsyncProcess"/>
    </wsdl:input>
  </wsdl:operation>
</wsdl:binding>

In the synchronous BPEL process scenario, we added the <wsdl:fault> information in the reply operation. For the asynchronous BPEL process scenario, we model the fault callback as a new operation in the callback portType as follows:

<wsdl:portType name = "HelloWorldAsyncProcessCallback">
  <wsdl:operation name = "processFault">
    <wsdl:input message = "client:ProcessFaultMessage"/>
  </wsdl:operation>
</wsdl:portType>

Information about the fault is then sent via the new callback operation to the client.

How to do it…

The asynchronous BPEL process does not return a fault in the same way as the synchronous BPEL process. For that purpose, we need to check the response SOAP message to see whether it contains the fault as follows:

Iterator<?> it = msg.getChildrenWithLocalName("fault");
if (it.hasNext()) {
  System.out.println("Fault occurred: " + msg.getFirstElement().getFirstElement().getText());
  return;
  }

If the fault exists, we execute the actions for solving the problems.

How it works…

We know from the previous recipes that calling an asynchronous BPEL process does not block the client. So, in order to retrieve information about the fault, we need to take a different approach as and when we call the synchronous BPEL process. We already mentioned that we defined another operation in reply to portType.

We now have a problem, when we send the response information back to the client. Namely, the client does not care, if the message is a success or failure. In any case, the onMessage method in the AxisCallback class is executed. Here is the reason why we needed to implement the additional code inside the onMessage method to check whether we received the fault from the asynchronous BPEL process.

There's more…

Another way of testing whether we received the fault as the response from the asynchronous BPEL process is to take advantage of the WS-Addressing fields in the SOAP Header class of the SOAP message. If we know the operation with which the asynchronous BPEL process is returning the faults to the client, we can check the <wsa:Action> element in SOAP Header as follows:

<wsa:Action xmlns:wsa = "http://www.w3.org/2005/08/addressing">
  processFault
</wsa:Action>

This element identifies the operation that was executed when the asynchronous BPEL process returned the response to the client.

See also

• For more information about asynchronous communication, check out the Calling an asynchronous BPEL process recipe