BPEL BUSINESS PROCESS FROM A WEB APPLICATION

INTRODUCTION

The very first activity of a business process is a receive activity. The receive activity is associated with an operation of an interface. To start a new instance of the process, a client needs to invoke that operation. A business process can appear to a client in three different forms:

A Service Control Architecture (SCA) component
An EJB
A Web Service

The web service option gives most flexibility. The client can be developed in one of many programming languages and platforms. Within WebSphere Integration Developer (WID), the client can be developed in a different enterprise application from the business process.

In this tutorial, we will learn how to develop a client for a business process that invokes the process as a web service. That is, to the client, the process is a regular web service.

PREREQUISITS

The focus of this tutorial is client development. We don’t intend to spend any time developing the business process. The client will invoke the PriceAvailabilityQuote process developed in a previous tutorial. You can either complete that tutorial or import the solution available in project interchange format.

It is expected that you already know the basics of process development and testing using WebSphere Integration Developer (WID).

If you are importing the solution, deploy it in the server and test the PriceAvailabilityQuote business process according to the tutorial.

BACKGROUND

Every business process implements an interface. An interface is an abstract definition of a service captured in a WSDL file. A business process that has been deployed in WebSphere Process Server is automatically exposed as a Web Service. Operations of that service can be invoked by a client by sending a SOAP request. To start a new instance of such a process, a client needs to invoke the operation of the Web Service that has been associated with the first receive activity of the process.

In the Business Integration view, expand SimpleModule->Business Logic->Processes. Double click on the PriceAvailabilityQuote process to open it in the editor. Select the receive activity. From the Properties view, select the Details tab.

Notice that the implemented interface is IPriceAvailabilityQuote and the operation associated with the receive activity is getPriceAvailabilityQuote. If you have not done the previous tutorials, take the time to study the interface. The getPriceAvailabilityQuote operation takes as input a QuoteRequest object and replies as output a QuoteResponse object. You can use the business object editor to view the schema of these objects.

EXPORT THE WEB SERVICE WSDL FILE

Before we can develop any Web Service client, we must generate a WSDL file that describes the abstract service interface as well as the SOAP over HTTP protocol binding and the SOAP endpoint (URL). Double click on SimpleModule->SimpleModule to open the assembly editor. Right click on the PriceAvailabilityQuote process and select Export->Web Service Binding. Click on Yes in the confirmation dialog. Then select soap/http as the invocation protocol. System creates a new export object called PriceAvailabilityQuoteExport. Save the assembly editor and wait for the build process to end.

The WSDL file is created as PriceAvailabilityQuoteExport_IPriceAvailabilityQuoteHttp_Service.wsdl in the root folder of the SimpleModule project. To view it in the Business Integration view, expand SimpleModule->Web Service Ports. The file can not be opened using the interface editor. To view the file, right click on it and select Open With->Text Editor. Understanding a WSDL file is always important. First, look at the line:

<wsdl:import namespace="http://SimpleModule/interfaces/IPriceAvailabilityQuote" 
 location="interfaces/IPriceAvailabilityQuote.wsdl"/>

This imports the abstract description of the service from the interface definition WSDL file instead of duplicating the content in this file. This is a very smart move by the WID developers.

Next, we will look at the line:

<soap:address
 location="http://localhost:9080/SimpleModuleWeb/sca/PriceAvailabilityQuoteExport"/>

This specifies the SOAP endpoint URL. The URL is valid for the development environment. If the client will be developed by a diieferent team or organization, you will probably need to change the URL to an actual host name and port number indicating the server where the process has been deployed.

Close the WSDL file.

CREATE THE CLIENT APPLICATION PROJECTS

Switch to the J2EE perspective. Right click on Dynamic Web Projects and select New->Dynamic Web Project. Enter QuoteClient as the web project name. System will automatically set the name of the enterprise application project to QuoteClientEAR. Click on Finish. Decline to switch the perspective to Web.

Start the WebSphere Process Server instance. After the server starts, add the QuoteClientEAR application to the server. Note: the client application and the business process will run in the same JVM. This happens in development only. In real life, they will most likely run in different JVM.

GENERATE THE CLIENT PROXY CLASSES

Client proxy classes provide a simple Java programming model to access a web service. From the menubar, select File->New->Other. Select Show All Wizards. Expand Web Services and select Web Service Client.

Click on Next. Enable the Web Service capability, if the system prompts you for it. Set the Client Proxy Type to Java proxy. Click Next. In this screen, you need to enter the location of the WSDL file exported in the previous step. Click on Browse, expand SimpleModule and select the WSDL file PriceAvailabilityQuoteExport_IPriceAvailabilityQuoteHttp_Service.wsdl. Click on OK. Click on Next.

In this screen, you enter the server runtime that the client will execute in and the project where the client proxy code will be generated. Click on the Edit button to choose the server runtime.

Expand Existing Servers and select WebSphere Process Server v6.0. As Web service runtime, select IBM WebSphere. This will generate additional files that make the client development compliant with the JAX-RPC standard. Click on OK.

As Client type select Web. As Client project select QuoteClient. System should automatically set the EAR project to QuoteClientEAR.

Verify that all entries are correct. Then click on Next. Choose No Security. Then click on Finish.

System generates the proxy Java classes, configures WEB-INF/web.xml and various other XML files as needed for JAX-RPC based client development. System also imports the WSDL file in the WEB-INF/wsdl folder. There is a slight problem. It does not import the various XML schema files that are imported by the WSDL files and describe the schema of the QuoteRequest and QuoteResponse business objects. To resolve this error, copy the following folders and paste them within the QuoteClient/WEB-INF/wsdl folder. You must use the Navigator view to copy and paste folders.

SimpleModule/types
SimpleModule/xsd-includes

The errors should go away at this point.

Now, let us investigate the client proxy classes. Expand QuoteClient->Java Resources->JavaSource->SimpleModule. Open the QuoteRequest class. This is a simple JavaBean class that represents the QuoteRequest business object. Close the file and investigate the QuoteResponse class. Finally, open the IPriceAvailabilityQuoteProxy class. This class represents the web service itself. It implements the service interface IPriceAvailabilityQuote. That means, it has an implementation of the getPriceAvailabilityQuote method that mirrors the operation by the same name offered by the service.

Close all open files.

CREATE THE SERVLET

In the J2EE perspective, in the Project Explorer view, expand QuoteClient->Deployment Descriptor: QuoteClient. Right click on Servlets and select New->Servlet. Enter GetQuote as the name of the servlet. Click on Next. Enter com.webage.servlets as the package name. Click on Finish.

Open the GetQuote class from under Java Resources->JavaSource->com.webage.servlets. Import the SimpleModule package:

import SimpleModule.*;

Change the parameters passed to the doGet method to more meaningful names as shown in boldface below.

doGet(HttpServletRequest req, HttpServletResponse resp)

Then, set the content of the doGet method as shown below.

protected void doGet(HttpServletRequest req, HttpServletResponse resp)
 throws ServletException, IOException {
 try {
 QuoteRequest qreq = new QuoteRequest();
 qreq.setBusinessID(req.getParameter("businessID"));
 qreq.setProductSKU(req.getParameter("SKU"));
 qreq.setQuantity(new Double(req.getParameter("quantity")));
 IPriceAvailabilityQuoteProxy proxy = new IPriceAvailabilityQuoteProxy();
 QuoteResponse qres = proxy.getPriceAvailabilityQuote(qreq);
 req.setAttribute("quote", qres);
 req.getRequestDispatcher("response.jsp").forward(req, resp);
 } catch (Exception e) {
 req.setAttribute("errorMessage", e.getClass().getName() +
 ": " + e.getMessage());
 req.getRequestDispatcher("request.jsp").forward(req, resp);
 }
}

Save changes and make sure that there are no compilation errors.

CREATE THE VIEW COMPONENTS

In the WebContent folder create a new JSP file called response.jsp. Switch to the Source view in the editor. Set the content of the <BODY> tag as follows.

<BODY> 
<H2>Price Quote and Availability Report</H2> 
<P> 
Quote ID: ${quote.quoteID} <BR/> 
Status: ${quote.statusCode} <BR/> 
Product SKU: ${quote.productSKU} <BR/> 
Unit price: ${quote.unitPrice} ${quote.currency} 
</P> 
</BODY>

Save changes. Create another JSP file called request.jsp in the WebContent folder. Set the contents of the <BODY> tag as follows.

<BODY> 
<h2>Price Quote and Availability Query</h2> 
<p><font color="red">${errorMessage}</font></p> 

<form action="GetQuote"> 
Business ID: <input type="text" 
name="businessID" value="${param.businessID}"/><br/> 
Product SKU: <input type="text" name="SKU" value="${param.SKU}"/><br/> 
Quantity requested: <input type="text" name="quantity" 
value="${param.quantity}"/><br/> 

<input type="submit" value="Get a Quote"/> 
</form> 
</BODY>

Save changes.

TEST THE CLIENT

Right click on the server and select Publish. Wait for publish to finish. If it fails, clean the projects (Project->Cleanfrom the menubar) and try to publish again.

Launch the following URL in a browser:

http://localhost:9080/QuoteClient/request.jsp

WEB APPLICATION TUTORIAL

Enter some values and click on Get a Quote. Make sure that you see a result page.

SOLUTION

The complete SimpleModule and the client projects are available here.

Invoking A Bpel Business Process From A Web Application Tutorial