BPEL and Java Cookbook

We have to set up a BPEL engine and a proper development environment. For the BPEL engine, we use the BPEL Process Manager from Oracle SOA Suite 11g. We also use JDeveloper as the development environment.

We will start with the HelloWorld example from the Oracle SOA Suite examples and will add additional functionality in the later recipes. For this recipe, we will unzip the HelloWorld example to our hard drive.

In the following steps, we will cover the actions we need to perform in order to deploy a BPEL process to the Oracle SOA Suite server:

After preparing the package for deployment with JDeveloper, we can deploy the BPEL process with the ant scripts. The scripts comes handy for continuous integration tasks in staging and production environments, where various testing and deployment tasks are performed automatically. A set of ant scripts comes with Oracle SOA Suite in order to compile, build, deploy/undeploy, and test the BPEL processes.

We first open the command prompt and change the directory to the example project home. For the deployment, we execute the ant script as shown in the following screenshot:

The command with which we started the deployment is as follows:

ant -f %Middleware_Home%\%SOA_Suite_Home%\bin\ant-sca-deploy.xml
  -DserverURL=http://localhost:7001
  -DsarLocation=.\deploy\sca_bpel-101-HelloWorld_rev1.0.jar
  -Doverwrite=true
  -DforceDefault=true

The ant script parameters have the following meanings:

Before the deployment starts, we have to enter the username and password of the BPEL server. Again, we open the Oracle Enterprise Manager Console in order to check whether the BPEL process was successfully deployed.

We are deploying the BPEL process on the BPEL server. The business process is now ready to be executed; however, we don't have any information about the business process besides the WSDL location of the business process.

In general, there are two approaches to designing the BPEL processes. The first one is the top-down approach, where we first develop the XSD schema and WSDL files, which is also called the contract-first approach . The next one is called the bottom-up approach, where we start from the already-written Java code and generate the XSD schema and WSDL files with tools.

The recommended approach when designing the BPEL processes is to first define the XSD schema, which contains the definition of the input and output parameters. This is also the proper place to put the various complex variables used in the business process.

The schema is later used by WSDL to define the BPEL process interface via the <wsdl: portType> element. Both WSDL and the XSD schema are packed into the deployment package and deployed to the BPEL server.

In order to call a synchronous BPEL process, we will develop a Java client using the JDeveloper wizard. After completing this recipe, we will be able to call a synchronous BPEL process from the Java client application.

With the wizard in JDeveloper, we prepare the Java proxy for calling the BPEL process using the wizards in JDeveloper. When the client is executed, it converts the parameters from Java types to XML types via JAX-WS. Then, the call to the BPEL process is performed, and after the BPEL process finishes, the client receives the result in XML. The XML types are then converted back to Java types.

We can define different options when creating the BPEL process proxy as follows:

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.

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.

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.

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:

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:

We modified the synchronous BPEL process to throw an exception when the input parameter says FAULT. With the check_fault condition, we check if the input parameter contains the word FAULT. The modified BPEL process is shown in the following screenshot:

We also need to define the fault structure in the XSD schema (HelloWorldProcess.xsd) as shown in the following code:

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

We define the element fault, which contains the element msg of the type string. We then define the fault message in the WSDL document as follows:

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

We also specify the fault in the <portType> and <binding> elements of the WSDL document (HelloWorldProcess.wsdl). In the following code, we omit the <binding> element definition:

<wsdl:portType name = "HelloWorldProcess">
  <wsdl:operation name = "process">
  <wsdl:input message = "client:HelloWorldProcessRequestMessage"/>
  <wsdl:output message = "client:HelloWorldProcessResponseMessage"/>
  <wsdl:fault name = "fault" message = "client:ProcessFaultMessage"/>
  </wsdl:operation>
</wsdl:portType>

We create the client proxy the same way we created it in the Calling a synchronous BPEL process from Java recipe. We now see the additional class ProcessFaultMessage.java. We use this class when the fault occurs in the BPEL process. The class is annotated with the @WebFault annotation, which indicates the service specific exception class as follows:

@WebFault(faultBean = "org.packt.bpel.sync.gen.Fault", targetNamespace = "http://xmlns.oracle.com/bpel_101_HelloWorld_jws/bpel_101_HelloWorld/HelloWorldProcess", name = "fault")
public class ProcessFaultMessage
extends Exception

The faultBean attribute defines the Java class that will transform the fault from XML to Java. Additionally, the namespace of the BPEL process is also defined.

We also need to modify the client proxy main class HelloWorldProcess_ptClient.java. Since it is possible that the BPEL process throws a fault, we must prepare our client code in advance for such a situation.

The business faults, as opposed to the runtime faults, are thrown by the applications when a problem with processing information occurs. Various situations can cause the BPEL process to throw a fault. The BPEL process might interact with web services and web service itself may throw a fault. Consequently, the BPEL process must react on the fault thrown by web service. When an exceptional situation occurs in the BPEL process, the fault is propagated to the client. As we can see, the newly created class ProcessFaultMessage.java extends the Exception class. We see that the BPEL faults correspond to the Exception class in Java with extensions. The BPEL process also provides the ability to define the compensation handlers. With the compensation handlers, it is possible to undo the actions that were executed during the BPEL process execution. We can consider the compensation handler as a block of code containing the activities performing the compensation tasks.

The BPEL specification defines two types of faults. In this, we meet the BPEL process fault; however, there also exists a set of standard faults.

The BPEL standard faults are thrown if the BPEL server encounters some conditions in the runtime environment that do not correspond to the specifications. This category also includes situations where the variables might not be initialized if transformation does not find the XSLT file or if some problems occur on the network.

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.

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.

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.

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.

We will need to extend the client proxy from the Calling an asynchronous BPEL process recipe, so we need to have the asynchronous BPEL process deployed and the client proxy ready.

First, we will update the response of the asynchronous BPEL process to include more XSD schema elements as follows:

<element name = "processResponse">
  <complexType>
    <sequence>
      <element name = "result" type = "string"/>
      <element name = "postalcode" type = "int"/>
      <element name = "temperature" type = "double"/>
      <element name = "person">
        <complexType>
          <sequence>
            <element name = "name" type = "string"/>
            <element name = "lastname" type = "string"/>
          </sequence>
        </complexType>
      </element>
    </sequence>
  </complexType>
</element>

If we now call an asynchronous BPEL process, we will receive more information. Also, the information is nested in the response.

The response from the BPEL process presents an XML document wrapped with the SOAP message. The XML format is not very friendly for programming in Java. That is why few implementations arise with the intent to simplify the transformation of XML to Java.

All the implementations mentioned here work with the same basic concept of serialization, deserialization, marshalling, and unmarshalling. In general, serialization and deserialization presents a way of transforming the data structures in a way that we can store them or transfer them between applications or over a network. The synonym for serialization, when we transform Java objects, is marshalling. Consequently, the synonym for the opposite operation, that is deserialization, is called unmarshalling.

The following mapping is used when we convert from XSD schema types to corresponding Java data types:

While the preceding table shows the default mapping between XML data types and Java data types, it is also possible to customize the mapping, usually through the configuration mapping file.

Applications written in Java usually do not operate with XML documents. If we want to call a BPEL process, we must also create a request. Until now, we used to build the request with the help of the XML document builder as follows:

OMFactory fac = OMAbstractFactory.getOMFactory();
OMNamespace omNs = fac.createOMNamespace("http://xmlns.oracle.com/HelloWorldAsync/HelloWordlAsync/HelloWorldAsyncProcess", "");
OMElement method = fac.createOMElement("process", omNs);
OMElement value = fac.createOMElement("input", omNs);
method.addChild(value);
//value.setText("Jurij");
value.setText("FAULT");

In the request, we have to know all the information, such as namespace, names of the XML tags, and, of course, the data itself.

To simplify the creation of a request, we can utilize the JAXB tools. First, we will take the Process.java class that we created with the wsimport tool. We include the class into the JDeveloper project. We need to add namespace info to the annotations in the class file as follows:

@XmlRootElement(name = "process", namespace = "http://xmlns.oracle.com/HelloWorldAsync/HelloWordlAsync/HelloWorldAsyncProcess")
@XmlElement(required = true, namespace = "http://xmlns.oracle.com/HelloWorldAsync/HelloWordlAsync/HelloWorldAsyncProcess")

We can now also change the createPayLoad() method in the ClientProxy.java class. We create an XML document from the DocumentBuilderFactory class as follows:

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
Document doc = dbf.newDocumentBuilder().newDocument();

Then, we create a JAXB context with the following:

JAXBContext jc = JAXBContext.newInstance(Process.class);

Finally, we create marshaller and serialize the request class as follows:

Marshaller marshaller = jc.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, false);
marshaller.marshal(req, doc);

The difference between the previous version of createPayLoad() and the newer version is that the previous version lacks transparency and clarity in the code. We can now fill the request data in the following way:

Process req = new Process();
req.setInput("JURIJ");

And call it as follows:

createPayLoad(req)