RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Developing Web Services: Handling Problems Along the Way  : Page 3

Once developers recognize certain design issues and patterns, the first barrier to Web services development is conquered. In this second article in a five-part series, we cut through another barrier with common sense guidance to help developers gain proficiency quickly and avoid the most common problems.

Learn the XML Exchange Models
Clearly, the definition and meaning of every aspect of the purchase order in the sample application needs to be flexible enough for all cooperating partners to use. One mechanism to facilitate this is to use document-exchange style.

The two primary models for invoking Web service methods are the RPC (remote procedure call) and the document-style messaging model. RPC messaging utilizes specific RPC coding conventions within the SOAP message in order to invoke a specific remote method. The document style approach is much more flexible, allowing for any type of XML document associated with any XML schema.

Document style is preferred for interoperability because it uses loose coupling of methods and data. Rather than pass the data as arguments to a method call, which is tightly bound by data type, the document style allows for a wide range of data to be passed and interpreted by the server. In the purchase order example, a client could make a single, asynchronous call to the server and would receive an associated document from the service. This cuts back dramatically on the number of calls to the server. The following is an example of what a SOAP response might look like for the purchase order using document style:

<SOAP-ENV:Envelope ...>
  		<name>Widgets, Inc.</name>
		<terms>Net 15</terms>
		<shipdate>10 Feb 2003</shipdate>

Document-style messaging can be more complex to implement, but it provides a number of benefits. First, document style offers you the full capabilities of XML to describe and validate a business document. With the RPC approach, the XML typically just describes a method call and its parameters. Second, document style does not require a strict contract between the client and the server, whereas an RPC message must be bound to a strict method signature.

To illustrate the differences between RPC and document style at the description level, Listing 1 contains WSDL that shows the RPC binding model, while Listing 2 contains WSDL for document style.

Also note that document style uses a literal encoding while RPC uses SOAP encoding. A SOAP encoding must conform to the SOAP 1.1 specification, while a literal encoding gives you more flexibility in using data types that map to XML schemas. While many developer tools allow different message styles, the industry appears to be standardizing on "document literal." The WS-I recently decided to disallow mixing of RPC and document encoding styles, in its Basic Profile Version 1.0.

A number of developer tools provide the ability to automatically map an XML document to some other language such as Java or C#. These tools can automatically create the necessary Java objects that represent all of the XML schema types referenced within the WSDL. In some cases, this is sufficient to get started with Web services. When more flexibility is required, the developer may have to write customized XML handling code, in which case either DOM or SAX is required for parsing.

No matter how you do it, XML processing can be complex and adds runtime overhead to your application. Choosing the appropriate parsing mechanism will minimize those effects. Because the purchase order example is document oriented, DOM is probably the better choice. It is also fairly small, so there won't be a lot of overhead when putting it in memory. SAX might be recommended if it were important to pull a specific tag from the document, e.g., if you had to extract only the PO number.

DOM will create a tree that represents the XML document output. From the top down, the code examines the nodes of the tree and extracts the data required to process the order. Typically, some or most of that information will be stored in a database. As the order is processed, a corresponding result document is constructed. This document is used to respond to the client and tell it the results of the operation. The following class code fragment generates the XML response for a purchase order.

import org.jdom.*;
public class POresult
   // This class constructs our PO result document
   public static void newPO(String docname)
     // Create a new purchase order document
     Element root = new Element(docname);
     DocType dt = new DocType("PO");
     Document doc = new Document(root, dt);
     root.setText("Purchase Order Results"); 
     // Create the toplevel node
     Element el = new Element("order");
     el.setText("Order Node");
     // This would help to debug our document
     // ...

DOM allows the application to traverse the entire document, which is appropriate for this example, as it requires the examination of every XML statement.

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date