Calling an asynchronous BPEL process from Java

This recipe explains how to call an asynchronous BPEL process from Java-based applications. Asynchronous communication is broadly used for long-running business processes. When a client invokes a long-running business process, it usually cannot wait long periods (days, weeks, and so on) for the response. Instead, the communication is closed, and a response from the business process is captured by listening for the callback. This recipe also uses the Apache AXIS package.

Getting ready

In this recipe, we call an asynchronous BPEL process. We enriched the sample scenario with the use of the Apache AXIS package. This allows us to receive an asynchronous callback from the BPEL process. We integrate the AXIS package into the JDeveloper environment simply by unpacking the AXIS package, and adding its jars into the JDeveloper project classpath.

How to do it…

We implement two classes. In the first class, we program the client that is calling the asynchronous BPEL process. In the second class, we prepare a callback class that is used to handle the response from the asynchronous BPEL process. Note that the asynchronous BPEL process is not sending a response to the client via a reply activity. Instead, the BPEL process is using the callback method, which contacts the client, of course, if one is listening.

1. Let us examine the ClientProxy.java class first. We start by creating the ServiceClient client and preparing the Options class to configure the ServiceClient client as follows:

     ServiceClient client = new ServiceClient();
     Options opts = new Options();

2. To configure the ServiceClient client, we set the parameters as follows:

   opts.setTo(new EndpointReference("http://medion:7001/soa-infra/services/default/HelloWordlAsync/helloworldasyncprocess_client_ep"));
   opts.setAction("process");
   opts.setUseSeparateListener(true);

   We instruct AXIS where the BPEL endpoint is, which actions we want to call, and the type of the listener (callback) we want to use. With the setUseSeparateListener call, we instruct AXIS to send a SOAP message over two separate channels, thus enabling the asynchronous communication.

3. We engage the addressing module of the AXIS package as follows:

   client.engageModule("addressing");

   With this line of code, we actually enable the WS-Addressing module inside the AXIS package. The WS-Addressing module provides transport-neutral mechanisms to address web services and messages. In AXIS, this package is a prerequisite for the asynchronous communication.

4. Finally, we set the options to the service client and fire a non-blocking request to the asynchronous BPEL process as follows:

   client.setOptions(opts);
   client.sendReceiveNonBlocking(createPayLoad(), new BPELCallback());

   The non-blocking request enables the client to continue its processing without actually waiting for the BPEL process to finish. The createPayLoad() method is a helper method used to create a request message for the BPEL process. The helper method is generating XML content out of the Java class through JAXB. We build the request with the help of the XML document builder.

5. The code which simulates further processing of the client is as follows:

   System.out.println("send the message");
   while (!isFeedback) {
     Thread.sleep(5000);
     System.out.println("waiting ....");
     }
   System.exit(0);

   The main thread is sleeping for five seconds, and after that period is over, it checks if the response was already received from the BPEL process. In the meantime, the client can process other requests. When the client receives the response from the BPEL process, it exits.

6. We created a code for handling the BPEL process response in the BPELCallback.java class. We implemented the onMessage and onComplete methods. When the reply arrives from the BPEL process, we print out the complete SOAP message as follows:

   public void onMessage(MessageContext messageContext) {
     SOAPBody msg = messageContext.getEnvelope().getBody();
     System.out.println(msg);
     }

7. When the transmission is complete, the method onComplete is invoked, and we signal the program from which we received the reply from the asynchronous BPEL process as follows:

   public void onComplete() {
     System.out.println("Transmission finished.");
     ClientProxy.isFeedback = true;
     }

8. After running the example, we check the client console output. As we can see, the message is sent to the BPEL process and the client program continues its work. When the response is retrieved from the BPEL process, we see that the message is retrieved within the callback handler, and that means the program exits.

   send the message
   waiting ....
   waiting ....
   waiting ....
   waiting ....
   <env:Body xmlns:env = "http://schemas.xmlsoap.org/soap/envelope/"><processResponse xmlns = "http://xmlns.oracle.com/HelloWorldAsync/HelloWordlAsync/HelloWorldAsyncProcess">
      <result>Hello </result>
   </processResponse></env:Body>
   Transmission finished.
   waiting ....
   [SimpleHTTPServer] Stop called
   Process exited with exit code 0

9. We also check the Audit Trail of the BPEL process. We see that the BPEL process received the message, executed the flow of activities, and at the end, contacted the client and sent a response to it as shown in the following screenshot:
   

How it works…

Asynchronous communication between the BPEL server and client is different than in synchronous communication. In synchronous communication, the BPEL process is invoked, the process flow is executed, and the result is returned to the client. The whole time the BPEL process is executed, the client is blocked. In asynchronous communication, the BPEL process is invoked and the communication is closed. We describe such a call as one-way invocation . When the BPEL process execution is finished, the BPEL engine initiates communication with the client and sends back the response via callback. An asynchronous BPEL process does not block the client. This means that as soon as the client initiates the asynchronous BPEL process, it can continue with other tasks. We can see that the asynchronous BPEL processes are used for long-running transactions where we cannot predict when they will finish. Such transactions can be found using human interaction through human tasks.

In order to enable asynchronous communication between the BPEL process and client, we use the WS-Addressing mechanisms. WS-Addressing provides transport-neutral mechanisms to address web services and messages. In the BPEL engine, the correlation mechanism is used in order to track multiple, long-running executions of the BPEL processes. Correlations help with tracking the route to the corresponding BPEL process instance. The correlation sets present a compound version of correlation, as they are composed of more individual correlations. In our example, the correlation information is hidden behind the scenes as WS-Addressing is automatically set to appropriate properties in communication between the BPEL process and client.

Note

Latest specifications of the WS-Addressing specification can be found at the following URL: http://www.w3.org/TR/ws-addr-core/.

Usually, both the BPEL servers as well as the client implementations already provide the libraries that support the WS-Addressing specification. The information about addresses resides in the SOAP Header class. When we initiate the BPEL process, the following attributes are set by the client:

• wsa:To: This identifies the asynchronous BPEL process which we want to start.
• wsa:ReplyTo: This identifies the address of the client to which the asynchronous BPEL process should return the response.
• wsa:MessageID: This identifies the uniquely defined number of a sent message. With this message ID, we match the sent request with the received response.
• wsa:Action: This identifies the action which should be executed on the asynchronous BPEL process.

Similarly, when the asynchronous BPEL process has finished its execution, the response is sent to the client. In the response SOAP Header class, the following attributes are set:

• wsa:To: This identifies the address of the client.
• wsa:Action: This identifies the response action name.
• wsa:MessageID: This identifies the uniquely defined number of a sent message. With this message ID, we establish a correlation between the request with the received response.
• wsa:RelatesTo: This identifies the message ID of the request. MessageID of the request and RelatesTo of the response are used by the applications to match the requests against their respective responses.
• wsa:ReplyTo: This contains information about where the response should be sent. For the response message from the asynchronous BPEL process, the element is empty.
• wsa:FaultTo: This contains information about the faults, if they exist.