Keep up with the Web service styles (and uses)

Control SOAP formats to avoid interoperability issues

By Mitch Gitman, JavaWorld.com, 10/03/03

It's a perfectly reasonable goal for a Web service toolkit and runtime engine: allow a developer to take a server interface, brand it a Web service, and automatically generate some client-side proxy code from it, all without ever having to eyeball an XML document.

That would be fine if all Web service platforms generated SOAP messages the same way. But, as Web service developers are finding out these days, they don't. And the formats some use by default to produce the XML in SOAP messages are losing ground as the preferred formats in the field. Worse, if two different Web service platforms provide differing levels of support for a certain formatting scheme, watch out when you need to run a client on one and a service on another.

The first part of this article explains the two central decisions developers make when forming SOAP messages—style and use—and how they relate to:

• The communication patterns that Web services support
• Existing Java specifications
• The high-level mechanisms for translating between Java methods and SOAP messages
• The fundamental Web service design choices

The second part shows how to control style and use—starting from both server-side Java and an XML Web service definition—using two Web service platforms:

• Apache Axis 1.1, an open source Web service toolkit and runtime engine.
• Systinet WASP Server 4.5.1 for Java, a commercial Web service toolkit and runtime engine. (Version 4.6 was recently released.)

Part 1: Untangling the terminology

Nowadays, Web service developers are being bombarded with catchphrases: "document/literal," "RPC-style," "message-style," and so on. And judging from mailing list threads and even seminar presentations, not only are many developers just confused about the terms' precise meanings, they are also confusing the terms with each other.

Actually, such misunderstanding is perfectly understandable, considering the imperfect evolution of Web service practices, as you'll see.

SOAP and WSDL XML

First, let's establish some basic, baseline knowledge of the XML in both a SOAP message and a WSDL (Web Services Description Language) document, which defines a Web service. (Speaking of imperfect evolution, the acronym "SOAP" has sloughed off its original meaning, Simple Object Access Protocol.)

A typical SOAP message viewed down to the second level follows:

<soap:Envelope
                                       xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" >
                                       <soap:Header>
                                       <!-- header element(s) here -->
                                       </soap:Header>
                                       <soap:Body>
                                       <!-- body element(s) here -->
                                       </soap:Body>
                                       </soap:Envelope>
                                    

The <soap:Header> element is not required for the core SOAP functionality discussed in this article and can be omitted. Essentially, the canvas we're trying to paint is the contents—the children, grandchildren, and so on—of the <soap:Body> element.

Here is an abridged version of a typical WSDL document viewed, for the most part, down to the second level:

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl"
                                       targetNamespace="your namespace here"
                                       xmlns:tns="your namespace here"
                                       xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soap">
                                       <wsdl:types>
                                       <xs:schema targetNamespace="your namespace here (could be another) "
                                       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                                       <!-- Define types and possibly elements here -->
                                       </schema>
                                       </wsdl:types>
                                       <wsdl:message name="some operation input">
                                       <!-- part(s) here -->
                                       </wsdl:message>
                                       <wsdl:message name="some operation output">
                                       <!-- part(s) here -->
                                       </wsdl:message>
                                       <wsdl:portType name="your type name">
                                       <!-- define operations here in terms of their messages -->
                                       </wsdl:portType>
                                       <wsdl:binding name="your binding name" type="tns:port type name above">
                                       <!-- define style and transport in general and use per operation -->
                                       </wsdl:binding>
                                       <wsdl:service>
                                       <!-- define a port using the above binding and a URL -->
                                       </wsdl:service>
                                       </wsdl:definitions>
                                    

The standard namespaces in a WSDL document are as follows: