Related Topics: Apache Web Server Journal

Apache Web Server: Article

Building a Real-World Web Service - Part 4

Building a Real-World Web Service - Part 4

It's time for Web services to prove their worth. They've gained enough attention for people to stop and notice, to wait and expect, to speculate and it's time to show people what the fuss is all about.

If the show fails to impress, Web services will slowly fizzle out like their predecessors. To make Web services succeed, the Web services community needs to choose winners from the competing Web services standards, vendors need to present a coherent message, and the community needs to keep stressing the true value of Web services: enabling e-business dialogue between business partners. This series of articles is focused on creating robust e-business dialogues using a mix of Web services standards and RosettaNet.

In Part 3 of the series, I showed you the components and tools necessary to construct and conduct the e-business dialogue, and how to install them. I constructed the public side of the e-business dialogue by building 6 of the 13 components necessary for the extended e-business scenario. In this article, I will show you how to build the private side of the process, thus completing the implementation of the extended e-business scenario. In this article I will also discuss the challenges of creating real e-business dialogues with Web services.

The Extended E-Business Scenario
The extended e-business scenario that we are building in this series is illustrated in Figure 1. To recap, the extended e-business scenario works as follows: after a particularly successful day of selling laptops, the Inventory Manager application at ACME realizes the inventories are running low, and it triggers the ACME PO requester process. The requester process then begins a public e-business dialogue with Laptops, Inc., placing a purchase order request.

Laptops, Inc., receives the purchase order request from ACME and immediately sends back a message acknowledging receipt of the request. The PO requester process at ACME receives the receipt acknowledgment and informs the Inventory Manager that the purchase order has been placed. The Inventory Manager returns to other activities and the PO requester ends the request process. Meanwhile at Laptops, Inc., the place PO process invokes the Sales Agent, an internal Web service, and passes ACME's purchase order request to the Sales Agent. The Sales Agent figures out which parts of the purchase order can be fulfilled and forms a purchase order confirmation that provides a detailed line-by-line account of the items it can provide. This confirmation is then passed from the Sales Agent back to the public place PO process at Laptops.

The process at Laptops then sends the purchase order confirmation to an ACME process that accepts purchase order confirmations. The ACME confirmation acceptance process invokes an internal Web service to inform the Accounts Service at ACME about the purchase. The ACME process next sends back a message acknowledging the receipt of the purchase order confirmation and concludes the purchase order e-business dialogue between ACME and Laptops, Inc. Laptops, Inc., receives this receipt acknowledgement and invokes an internal Web service to its shipping department so that the order can be shipped to ACME.

As you can see, there is a lot of activity taking place in this scenario. Before we get into the implementation end, it is important to explore how to create realistic processes, and areas where Web services have room for improvement.

Building Reliable Asynchronous Processes
To enable a realistic public process between the two business partners, it is necessary to create it as an asynchronous process, the key to flexible and longer running e-business dialogues. Remember that BPEL processes are layered over Web services, adding business processes to the basic functionality provided by Web services. BPEL processes introduce stateful interactions, co-relate independent Web services, and define partners, activities, data containers, condition statements, and many other features to provide flexible and more descriptive e-business dialogues.

Web services perform synchronous operations by default. This means that a service requester sends a request and waits until a response is received from the service provider.

To create a synchronous purchase order process where ACME sends a PO request to Laptops, Inc., the only component required would be to build a PO Web service at Laptops, Inc. This service would take the request from ACME, process it, and send a response on the same connection, within a matter of seconds. What happens if the connection is lost? What if it takes longer to furnish a response? While ACME is waiting, how will it know if Laptops is busy working on its requests, or if Laptops never received the request? This method of communication has two problems: it is synchronous and unreliable.

The "business transactions" are typically longer running activities that might take hours to respond, and in these transactions, both parties need to rest assured that the messages are being received. A simple way to enable reliable messaging is for each party to send back a simple "signal" acknowledging receipt of the message. In this mode, even if Laptops, Inc., takes two hours to reply to the PO request, it will acknowledge the receipt of the PO request immediately. This way ACME knows that the request order has been received; otherwise ACME might start sending the same PO request repeatedly, causing confusion and hindering the e-business dialogue.

To enable asynchronous communication using Web services, Laptops, Inc., needs to implement a Web service but so does ACME. When ACME sends a purchase order request, it receives only a receipt acknowledging that request. Next, Laptops, Inc., would invoke a Web service on ACME and send the purchase order confirmation as a request, and receive a receipt acknowledging the purchase order confirmation as the response. For the real-world Web service, I have extended this simple idea into BPEL processes, to allow for stateful, asynchronous, reliable interactions between business partners.

Room to Improve in BPEL4WS and WSDL
The discussion of building real-world Web services would not be complete if I didn't point out that WSDL and BPEL4WS are both young efforts, with some inadequacies that need to be addressed in "version 2" releases. The encouraging news is that the W3C has started several groups to look at various aspects of Web services including the Web Services Architecture Group, the Web Services Description Group, and more recently, the WS Choreography group. These groups include veterans from EDI, RosettaNet, and ebXML, who will hopefully keep the groups from reinventing the wheel, and leverage solutions from the more mature standards.

If we look strictly at the WSDL side, the Web services definition encourages a relationship that is more of a service provider serving an anonymous service requester. A WSDL file simply tells a client how to access the services; it has no provisions for the service provider to find out about the service requester. A real e-business dialogue requires a more peer-to-peer role, meaning that both partners can be providers and requesters. In WSDL, the service provider cannot initiate the dialogue; it has to wait for a request and can only send a response. This setup makes it difficult to establish colleague-to-colleague relationships, and awkward to construct dialogues that require asynchronous operations.

BPEL4WS is a very recent effort and will take time to mature. One of the problems of working with BPEL was using an even younger alpha version BPWS4J engine. The BPWS4J engine does not implement the entire BPEL4WS spec, which caused a fair share of problems. The most significant problem is that at the time of this writing, the BPWS4J engine allows only RPC calls. Sending the document as an RPC call causes problems when you have to pass larger documents to your BPEL process, as it is a tedious process.

Since BPEL4WS is layered on top of Web services, a simple e-business dialogue becomes quite complicated to build. The public process between business partners should really take two public interface definitions; instead, it takes three BPEL processes and two Web service definitions.

Building the E-Business Dialogue
Now that we've discussed how to build reliable asynchronous processes, and the challenges we face building them, it's time to finish the construction process we began in Part 3 of this series. But first we need to acquaint ourselves with the languages, tools, and components involved in the building process.

We need a variety of languages and tools to build and execute the e-business dialogue. We are using the definition of an e-business dialogue, the choreography and messages definitions, from RosettaNet. The e-business dialogue is written using a mix of WSDL and BPEL4WS, which are both XML-based languages, and the internal Web services interact with applications written in Java.

The tools needed for creating and conducting the scenario are Eclipse, BPEL Editor, Tomcat, and the BPWS4J engine. Eclipse is needed to write and compile Java classes. It's also needed for the BPEL Editor plug-in to build and compile the BPEL process. We need the BPWS4J engine, which runs on Tomcat, to execute a business process. To get in-depth descriptions of these tools and how to install them, please refer to Part 3 of the series.

The Components
Thirteen components are needed to conduct this end-to-end business scenario (see Table 1). The public part of the e-business dialogue only requires five components, but since that may leave readers wondering how to tie the back-end systems to the public process, I am building the extended e-business scenario, complete with the back-end hooks.

Inventory Manager
This Java application resides on the enterprise server at ACME. It sends an internal purchase order request to the ACME PO requester process using SOAP calls. The Inventory Manager receives a receipt acknowledgment verifying that the purchase order has been placed.

It is important to understand how Apache SOAP works to understand how Java applications can interact with Web services. The Apache SOAP user guide is available online at Listing 1 shows how Inventory Manager makes the call.

The Inventory Manager makes a SOAP call to the PO Requester Web service. The call object needs to know the URI where the call will be invoked; this URI is provided by the BPWS4J engine after the ACME PO requester process is installed. Next, the method that the call will invoke is set. This method name matches the operation name of the PO Requester Web service. The Inventory Manager performs an RPC-style SOAP call; therefore, the call object needs to know the parameters passed to the method. Note that the name of the parameter, PORequest, matches the part name of the input message on the PO Requester Web service.

PO Requester Web service
This internal Web service, written in WSDL, resides on the ACME server and is consumed by the ACME PO requester process. The Inventory Manager sends its purchase order request to this Web service, and since the process is layered on top of this Web service, it takes care of the request. In our example, the requester Web service returns a receipt acknowledgment from Laptops, Inc., that the purchase order has been received. The complete source code file is available for download from; Listing 2 is the snippet we are interested in.

PO Receiver BPEL process
This BPEL process is a public e-business dialogue component at ACME. Its job is to receive the purchase order acceptance sent by Laptops, Inc., send back a receipt acknowledgment to Laptops, Inc., and invoke the Accounts Service internally at ACME. The Accounts Service is a Java application, but since BPEL processes can interact only with Web services, we need to define a Web service "wrapper" for the Java application. Let's start by making the necessary additions to the process. First, we need to add the Accounts Service as a partner:

... <partner name="Accounting"

Next, we need a container definition, see PurchaseReport container below:

... <container name="PurchaseReport"

The process invokes the service using a normal invoke activity:

<invoke name="invoke" partner="Accounting"
operation="reportPurchase" inputContainer="PurchaseReport"

To see how this invoke will result in the activation of the Java application, let's look at the Accounts Service Web service.

Accounts Service Web service
This Web service, written in WSDL, is an internal Web service that enables the process to invoke a Java application (see Listing 3).

It's important to note that the parameter of the method call in the Java application matches part name "purchaseReport" of the input message "reportPurchaseMsg". Having defined the messages and the portType, the bindings section will map the Web service to the Java application (see Listing 4).

Listing 4 shows that the binding type is "JavaBinding". The binding also contains a typemap, and in our case it is simply mapping the xsd:string to java.lang.String. The next lines show that the operation reportPurchase in the Web service definition maps to the reportPurchase method in the Java class. The service element identifies the port and bindings as Java, and provides the address of the class. To make the class accessible, you can add it to a WAR (Web archive) file, and deploy it on Tomcat, or an easier method is to simply place the class file on the "\ApacheGroup\Tomcat4.1\webapps\bpws4j\WEB-INF\classes" directory.

Now let's look at the Java class this Web service is bound to.

Accounts Service application
The Accounts Service application is used to report purchases made by ACME. It has the single method reportPurchase that returns a String and takes a String named purchaseReport as a parameter. The parameter name is identical to the input message part name in the accounts service Web service definition.

The AccountsService simply writes out the purchase report and a time stamp to a file named "PurchaseReport.acme" (see Listing 5).

Let's look at another example, this one defined at the Laptops, Inc., side. At the end of the Laptops place PO process, an internal Web service is invoked with a ship order. To enable this the partner and container definitions are created and then the Web service is invoked:

<partner name="internalShipping"
<container name="internalShippingOrder"
<invoke name="invokeShipping" partner="internalShipping"
operation="shipPO" inputContainer="internalShippingOrder"

The above is just the snippet of code I want to describe here; I encourage you to download the entire source for this article. Looking back at the definition of the invoke activity, it is important to note that the input container is the message sent as a "request" to the service being invoked, and the output container is the message being sent as the "response" from the invoked service. The input and output containers should contain the same "types" of parts as those expected in the input and output messages of the port type being invoked in the target Web service. Let us now look at the Laptops Shipping Service that the process interacts with.

Laptops Shipping Service Web service
The Web service shown in Listing 6 has an operation named "shipPO" that takes a message with two parts: the purchase order acceptance, and the receipt acknowledgment that ACME has received the purchase order acceptance. Listing 7 shows the binding information.

Again, we see that the Web service is using Java bindings, the only mapping required is to show xsd:string maps to java.lang.String. The Web service operation name is shipPO, which is also the method name of the Java class. In the service definition section, we see that the class is ShippingAgent. To make it work, we need to drop it in "\Apache Group\Tomcat 4.1\webapps\bpws4j\WEB-INF\classes". Listing 8 shows the definition of the Shipping Agent.

The Shipping Agent is a simple Java application that takes a confirmed purchase order and its receipt acknowledgment and writes them into a class named ShipOrders.laptops.

Using similar methods to define Java bindings, we can add the remaining components to the Laptops place PO process. Please look at the full source code to see the definitions of all 13 components used in this article.

Running the Scenario and Checking the Results
I've designed this scenario to be deployed on separate machines; to deploy it on a single machine, you'll need to run two instances of Tomcat (instructions are available in Tomcat's read-me file). To enable the Java applications for the processes, you will need to place the class files on the Tomcat server at: "\Apache Group\Tomcat 4.1\webapps\bpws4j\WEB-INF\classes". Next, launch Tomcat and deploy the processes following the instructions given in Part 3.

The scenario will create three files: ShipOrder.laptops, PORequest.laptops, and PurchaseReport.acme. The Inventory Manager and the Sales Manager come with hard-coded purchase order requests and purchase order acceptance based on RosettaNet purchase order processes. To check the results, simply inspect the three files created by the scenario.

A Summary of Building a Real-World Web Service
I started this series to prove that Web services can be used even today to conduct real e-business dialogues. The series covered important e-business architecture issues and constructed the real-world Web service piece by piece. In Part 1 I explained e-business dialogues, RosettaNet, and WSDL, and I demonstrated how to build a Web service definition using components from RosettaNet.

In Part 2 I talked about choreography and e-business standards like RosettaNet and ebXML, which provide choreography and other advanced e-business dialogue functions. I also explained how BPEL works and ended the article by creating an abstract business process that could be used as a collaboration agreement between business partners.

In Part 3 I explained how to create executable asynchronous business processes and how to implement these processes, providing the list of tools to be installed and instructions for installations. I ended the article by demonstrating the purchase order process running between two business partners.

In this installment, I have shown you how to hook your BPEL processes to your back-end Java applications. I also explained some of the challenges of building the real-world Web service. We now have a running e-business dialogue scenario that is based on RosettaNet concepts and components, described in WSDL and BPEL, built using open source tools, and deployed on an open source application server.

Are we there yet? Almost. In the real world, we cannot exchange this sensitive data on open networks without adequate protection. The next installment in this series is all about providing a secure real-world Web service. So, are Web services secure? Tune in next month to find out the answer.

More Stories By Suhayl Masud

Suhayl Masud is an experienced software architect with over 8 years of experience in designing and developing e-Business and e-Commerce systems. Suhayl recently helped RosettaNet develop the next generation of e-business processes. Suhayl has worked extensively with Java and Smalltalk, and served as an instructor and mentor for Fortune 500 companies

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.