Developing Web Services: Handling Problems Along the Way

he Web services concept?connecting standardized components via well-advertised interfaces?seems as if it would make for simple programming. While there are developer tools available to ease the creation process, there is a need for detailed knowledge of the programming domain. There are several key implementation choices that make the difference between a difficult project and one that sails along.

The first article in this series described good design practices; this article will discuss specific development techniques that will get you quickly past the more complicated programming challenges that will arise.

These techniques fall into four general categories:

  • Enhancing Interoperability
  • Adding Security to your Web Service
  • Choosing the Right Development and Testing Tools
  • Preparing for Deployment

Enhancing Interoperability
The core technologies at the heart of Web services?WSDL, SOAP, and UDDI?are designed to ease interoperability. In particular, SOAP, a protocol built upon XML, is the fundamental Web service transport technology. Because XML is a widely accepted technology for passing structured data, it is tempting to believe that SOAP messages provide interoperability. But, XML is not the “silver bullet” for solving integration problems.

To achieve true interoperability across multiple companies, standard syntax and semantics are both required. For example, let’s define a simple data structure for a purchase order. The over-simplified purchase order example will contain only the company name, product identifier, and price.

   "Widgets, Inc."    123456    "$59.95" 

This example represents pricing data as a string. If a partner were to instead represent pricing data as a floating-point number, data type errors would be likely to occur. Therefore, agreement among partners about how to handle data is essential. XML solves data typing issues through the use of XML schemas. The following example shows how each element in the purchase order can be designated a specific data type:

                                                               

With the XML schemas defined, you can create the WSDL that defines the input and output operations. In this scenario, there might be an XML type defining the “order_request” and another defining the “order_response.” The following WSDL could be used to tie the request and response messages together:

                                                                                  

In the WSDL example above, the request and response messages are mapped to the specific XML schema types. Then, a specific operation is defined, called “placeOrder” that connects the request with the response message. This simple example illustrates how XML schemas can be used to identify specific data types that are required for a Web service and how WSDL messages and operations can be constructed. Developers wishing to use the service (for example, those who work for your partners) then know the exact contract or interface required.

Things get more complicated when you try to understand the meaning, or underlying semantics, of the data. In my fictitious example, there are two major assumptions about products and prices: First, that products will always be represented with numbers, and second, that pricing can be expressed in U.S. dollars. Both assumptions are unlikely to be tenable in the real world.

Neither XML nor WSDL can solve such semantic issues. They must be agreed upon in advance by the various partners in the interaction, and a mechanism to translate from one structure to another must be developed. Technologies such as XSLT (the Extensible Stylesheet Language Transformations) and XPath (the XML Path Language) meet that need.

There are tools available that provide direct support for mapping between different XML formats or schemas. For example, with Cape Clear’s CapeStudio developers can input two XML schemas, define mappings between the types, and the product will automatically generate an XSLT document for translation. BEA’s WebLogic Workshop provides a Map and Interface Editor in which you can easily set up XML mappings between incoming XML requests and back-end logic. Other platforms can utilize handlers to pre-process incoming SOAP requests. Here, a developer could introduce XSLT logic to transform the XML document if necessary.

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:

     	  		Widgets, Inc.  		123456  		59.95		10%		Net 15		10 Feb 2003	     

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.

DOM vs. SAX
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");     root.addContent(el);     // This would help to debug our document     System.out.println(doc);     // ...  }}

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

Adding Security to your Web Service
As you learned from the previous article in this series, there are levels at which security can be applied to a Web service. For this example, there are two basic requirements: validation of the entity making the request and hiding the data from non-partner companies. To achieve these objectives, the best choice is message-level encryption. XML digital signatures will be used for data integrity, authentication, and non-repudiation. I want to validate that all SOAP messages for purchase orders come from well-known entities and that they have not been modified.

XML Encryption will be used to add the confidentially aspect, indicating that the data can be viewed only by the receiver. In Listing 3, the payment information is encrypted, and there is a digital signature identifying the customer.

I could have also chosen to encrypt the entire XML purchase order. This example will secure XML documents, but won’t directly address how security is applied to Web services technologies such as SOAP.

WS-Security is the industry’s first attempt to define XML-related security specifically for Web services. This involves extending SOAP to add Web services security tags to the SOAP header. WS-Security primarily defines a set of delimiting tags to be used in the SOAP header for adding identification, authorization, and encryption to the SOAP message. You can find the full specification at the World Wide Web Consortium Web site (see “Related Resources,” left).

Choosing the Right Development and Testing Tools
Commercial development tools are an asset in the Web services creation process, and developers should make it their goal to leverage their existing tools and development environments as much as possible. To that end, find out whether Web service extensions or plug-ins have been created for the IDE that you use. Microsoft’s Visual Studio .NET and the DotGNU Portable .NET both support the Web services creation for .NET. In the J2EE world, Borland provides an extension to JBuilder, Borland Web Services Kit. There are also standalone products, such as CapeClear and Systinet. Some tools provide plug-ins to other development environments, like the Eclipse open-source framework.

If you’re going to adopt a new development environment, there are important questions to ask:

  • Does the tool support the creation of document-style services?
  • Does it support the creation of asynchronous messages?

Some tools let you select what document model you want to use, while others provide simple mechanisms for creating asynchronous requests.

  • How does the tool support or extend current standards?
  • What specific languages (Java, C/C++, etc.) can be imported into the tool?

Look for tools that can automatically generate Web services components. This can reduce the learning curve for the developer and increase productivity. It can also help isolate the developer from changing specifications.

SOAP monitoring tools can assist with another important aspect of development: the debugging process. A SOAP monitoring tool, or sniffer, is included in many tools and allows a developer to view SOAP requests and responses that flow through the application.

A sniffer acts as a proxy server, sitting in front of the actual Web service host. Requests are sent to the proxy, which traps the SOAP messages that come in and out, and displays them in a graphical window for the developer.

There are many other aspects of debugging to consider. In particular, runtime issues such as availability, performance, security, and scalability all must be tested, both during development and in production. For this, some form of integration with your management platform is essential.

Building a Web Service
Finally, it is important to consider the approach that will be used to build and deploy your Web services applications. Using an automated build tool can greatly enhance developer productivity. One of the more popular build tools on the market today is an open source offering called Ant.

You can think of Ant as a next-generation Make utility. Like Make, it can be used to simplify and automate almost any build process. Unlike Make, it is based on Java and XML. This makes Ant much more portable across multiple platforms. Because Ant uses XML, it is component-based?you can easily add new types of build targets or import from existing build files, etc.

Ant can also be used to help generate Web services components. The example below defines a task for creating WSDL from a Java class and a task for creating Java client proxies from WSDL. From these tasks, specific targets can automatically generate the Web services components. Overall, this approach can speed up the develop-deploy-test cycle.

                   

Some products, such as Collaxa and BEA WebLogic, provide Ant support out of the box, which makes it even easier to integrate Web service builds into your environment. Ant appears to be the defacto standard build tool for Web service, but many companies have their own internal build environments. Regardless of what build tool you use, the important thing is to follow the model of continuous integration?building and deploying early and often.

Testing Your Web Service
Hand-in-hand with debugging is the problem of testing your Web services. There are many facets to testing, such as validating the interface functionality, performance analysis, and load balancing for scalability.

Because Web services are programmatic interfaces to functionality, they are good candidates for automated testing tools as developers can quickly simulate thousands of virtual users accessing the Web service under different system conditions. Things to look for in a testing tool include:

  • Performance Testing. Look for testing tools that can measure the performance (and scalability) of a Web service. A good testing tool can help find performance bottlenecks.
  • Functional Correctness. The testing tool should make sure your Web service does what it’s supposed to do, even under high load.
  • Auto-Generation. Being able to generate different combinations of input randomly can get you started more quickly and can also help with regression testing.
  • WSDL Support. The testing tool must be able to input a given WSDL and automatically generate a set of starting test cases based on the data types, methods, and operations defined within the WSDL.
  • Build Integration. The concept of continuous integration implies that you should build, deploy, and test as often as possible. To do this, the testing tool must be able to run both inside an environment and as a standalone process from the command line. Developers and testers must be able to execute a single command line script to run through the test cases.

Youll find several vendors already offer Web services testing tools that include some or all of these features. For example, HP provides the OpenView Transaction Analyzer product that enables you to diagnose performance bottlenecks for both J2EE and COM-based applications. Empirix has a set of testing and monitoring tools, including FirstACT, an automatic test-case generator. Another testing tool is Parasoft SOAPtest, an automated inter-module testing tool that emulates both the SOAP client and SOAP server and allows early module testing.

The biggest challenge to testing your Web services is that there is no user interface, so all the testing must be accomplished programmatically. Your strategy should be to develop a test suite, or set of tests, that can be run both automatically, such as during the night, and by non-development testing personnel. Also, testing should be developed throughout the project, as part of design and development, rather than waiting until implementation is complete. This will ultimately save time and improve quality.

Prepare for Deployment
Once you release your Web services to production, you want to feel assured that customers will find them robust, reliable, and efficient. The price of that assurance is to consider how to implement and test for functionality, security, reliability, and scalability. You may have to tackle other Web service deployment issues, too, based on customer requirements and your IT infrastructure.

A successful Web service implementation starts with sound design, but many issues are encountered during development and deployment that are not known when the first designs are done. By planning ahead and studying the component parts of your development process, you can plow easily through troubles when they arise. Remember these key techniques and you’ll avoid most problems:

  • Use XML schemas to clearly define the message data types being exchanged between Web services.
  • Provide a WSDL class for your Web service to enhance interoperability.
  • Use document-style messaging to enhance flexibility and reusability of your Web services.
  • Understand when customized programming might be required.
  • Consider XML security and XML digital signatures to encrypt and secure your SOAP messages.
  • Evaluate available development and testing tools, with special emphasis on Web services-specific features.
  • Determine how to utilize deployment and management data to facilitate development.

Share the Post:
Share on facebook
Share on twitter
Share on linkedin

Overview

Recent Articles: