Most common WSDL stumbling block

When it comes to helping people debug WSDL issues, the #1 overlooked and misunderstood problem is usually whether to specify type or element as the attribute to the element. If you are creating web services and defining WSDLs you must understand this significant difference as it will effect the consumers of your services.

All my examples and information where referenced from the book Building Web Services with Java. I would highly recommend this book.

Simple WSDL
Let's first begin with snippets from a simple WSDL.

<definitions name="PriceCheck">
 <types>
     <xsd:schema>
         <xsd:element name="sku" type="xsd:string"/>
         <xsd:complexType name="availabilityType"
             <xsd:sequence>
                 <xsd:element ref="sku"/>
                 <xsd:element name="price" type="xsd:double"/>
                 <xsd:element name="quantityAvailable" type="xsd:integer"/>
             </xsd:sequence>
         </xsd:complexType>
         <xsd:element name="StockAvailability" type="availabilityType"/>
     </xsd:schema>
 </types>
 <message name="PriceCheckRequest">
     <part name="sku" element="sku"/>
 </message>
 <message name="PriceCheckResponse">
     <part name="result" element="StockAvailability"/>
 </message>
 <portType>
    <operation name="checkPrice">
     .......
 <binding>
 .......
 <service>
 .......
</definitions>

WSDL Parts
A part element is made up of two properties: the name of the part and the kind of the part. The name property is represented by the name attribute, which must be unique among all the part child elements of the message element. The kind property of the part is defined as either a type attribute (a simpleType or complextType from the XSD schema type system) or an element attribute (also defined by referring to an element defined in the XML schema). You can't use both an element attribute and a type attribute to define the same part.

The choice of using element or type when defining the part is very important. The most common mistake is using the type attribute and referencing an XSD element or using the element attribute and referencing an XSD simpleType or complexType.

Use of element
When you use the element attribute, you're specifying that the SOAP should be precisely that XML element. For example, the PriceCheckRequest example specifies that the XML element named sku must be used as the body of the messsage. Here is a snippet of what the SOAP would look like:

<soap:Envelope>
 <soap:Body>
     <sku>123</sku>
 </soap:Body>
</soap:Envelope>

Note how the SOAP contains exactly the specified sku element. The element attribute should be used to define the type of the part when the Web service is meant to be document oriented (which is defined in the binding). Whenever the element attribute is used, its value must refer to another global XML element defined or imported in an XML schema.

This not only applies to requests but responses as well. For example, here is what the SOAP would look like for PriceCheckResponse:

<soap:Envelope>
 <soap:Body>
     <StockAvailability>
         <sku>123</sku>
         <price>100.0</price>
         <quantityAvailable>12</quantityAvailable>
     </StockAvailability
 </soap:Body>
</soap:Envelope>

Use of type
The PriceCheckRequest could have been built differently, using a part defined with the type attribute, like this:

<message name="PriceCheckRequest">
 <part name="sku" type="xsd:string"/>
</message>

Here is an example of the SOAP using the RPC-style where checkPrice is the name of the operation defined in the WSDL:

<soap:Envelope>
 <soap:Body>
     <checkPrice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <sku xsi:type="xsd:string">123</sku>
     </checkPrice>
 </soap:Body>
</soap:Envelope>

Summary
That is the difference between defining your part as an element or type. The most common style to use is document oriented and therefore the parts must use elements. If you use type in your parts, you need to use the RPC style.

Unfortunately all this isn't well documented. However there is good news. In WSDL 2.0 message and part elements have been removed. Instead you would use the names of the XML element declarations directly in the operations input, output, and fault messages.

Test Driven Development ROI

Ever think about the true benefits of tests and the value they provide you and your company? This article basically challenges developers to consider the ROI (Return On Investment) of every test. It has had a big impact on my software development habits by making me examine the benefits vs. the costs of writing tests.

Here is one of his most interesting comments: "... the developer is concentrating on testing before "coding" - the primary function is hence the development of tests, leading to a situation of "test-oriented development. This is where the production of tests becomes the overriding concern and output of a team, with the development of required functionality being secondary. When this occurs, the design, quality, and scope of the tests all become greater than that of the system actually being created". I am a firm believer in unit tests, but I hope I never fall into that category. We have a saying here at work, "I can get you about 90% confidence, but it's going to cost a lot to get that other 10%".

Oh yeah, its now Test First Development.

Also here is a follow up article to the original link above: When TDD Goes Bad #2. In it the author explains Mock oriented development and the lack of integration tests.

My de facto standard on WSDL styles

Here is my de facto standard reference on WDSL styles; bookmark it! When I first started writing Web Services I never knew their were 2 styles and 2 uses, or even that there was a style. As I gradually learned more about WSDLs it was difficult to find a good explanation of the different combinations. This article, written by Russel Butek on IBM developerWorks, explains how you determine which combination of style and use to choose. He provides advantages and disadvantages of each and shows WSDL and SOAP messages for each combination.

Overall when creating a Web Service you have 4 style/use options:

1. RPC/encoded
2. RPC/literal
3. Document/encoded
4. Document/literal

Along with these four is a recently new pattern which is commonly called document/literal wrapped.

Please read this article if you are unfamiliar with the different styles and uses. In general the most common style used is document/literal wrapped with document/literal in second. Most newer SOAP Stacks actually don't support RPC anymore; for examlpe cxf (aka xfire) and axis2.