Designing a WSDL (Web-Services Description Language) file

This article is aimed to get a very clear picture of various binding styles and their use while designing a WSDL file. I have tried my level best to put description in a very simple and precise manner.

The Web- Service Description Language (WSDL ) is XML based service description often pronounced “Whiz-Dull” that describes the public interface to the web-service. It abstractly describes the supported operations and messages and how they are bound to concrete network protocol and message format.

Although there are lot of discussions going on various binding style and their use, there still lies the confusion on how to determine which combination of style and use to apply while designing WSDL file.

The element of the WSDL contains a pair of parameters that influence the form of the resulting SOAP messages: binding style (RPC or document) and use (encoded or literal).

This gives you four style/use models:

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

Add to this collection a pattern which is commonly called the document/literal wrapped pattern and you have five binding styles to choose from when creating a WSDL file.

The terminology here is very unfortunate: RPC versus document. These terms imply that the RPC style should be used for RPC programming models and that the document style should be used for document or messaging programming models. That is not the case at all. The style has nothing to do with a programming model. It merely dictates how to translate a WSDL binding to a SOAP message. Nothing more. You can use either style with any programming model.

Likewise, the terms encoded and literal are only meaningful for the WSDL-to-SOAP mapping only while the actual meanings make a bit more sense.

According to the WSDL 1.1 Specification, the key differences between binding styles are as follows :-

RPC Style

• This style specifies that it has an element with the name same as
that of service method name called as wrapper element.

• This element, in turn, contains an entry for each parameter and return value of this method

• This style mandates that the parameters specified must be in the specific parameter order

Document Stlye

• When the attribute is set to document style, the client understands that it should make use of XML schemas rather than remote procedure calling conventions

• This style does not contain any wrapper element. Instead the message parts appear
directly under the element

• The contains what the sender and receiver agreed on as an XML document

Within those styles, you can also have literal use and encoded use.

Literal

• Each message part references the concrete schema definition using either the element or type attribute

• In other words, data is serialized according to the given schema agreed upon by the sender and receiver, usually expressed using the W3C XML Schema Specification

Encoded

• Each message part references an abstract type using the type attribute only

• The encoding used is SOAP encoding which specifies that the serialization will be done according to the SOAP rules. SOAP 1.1 has the set of serialization rules defined which specify how objects, arrays, and structures should be serialized

Lets discuss the Pros and Cons of various style/use combinations. As mentioned earlier, we have 5 different style/use combinations

1) RPC/encoded style

Strengths
• The WSDL is very much straightforward
• The operation name appears in the message, so the receiver has an easy time dispatching this message to the implementation of the operation.

Weaknesses
• SOAP message contains xsi :type encoding attributes which is usually just overhead and degrades throughput performance
• However, it’s difficult to validation to message because the service method name is not defined in the schema, but is instead a WSDL definition.
• RPC/encoded is not WS-I compliant. Thus makes it difficult for other types of clients to read the WSDL and generate appropriate stubs on the client side to call the service.

2) RPC/literal style
The RPC/literal WSDL looks almost the same as the RPC/encoded WSDL except the use in the binding is changed from encoded to literal. The SOAP message for RPC/literal is same as RPC/encoded with the type encodings been removed.
Here are the strengths and weaknesses of this approach:

Strengths
• The WSDL is still about as straightforward as it is possible for WSDL to be.
• The operation name still appears in the message.
• SOAP message does NOT contain xsi :type encoding attributes
• RPC/literal is WS-I compliant.

Weaknesses
• You still cannot easily validate this message since the service method name is not defined in the schema, but is instead a WSDL definition.
What about the document styles? Do they help overcome this weakness?

3) Document/literal

The WSDL for document/literal changes somewhat from the WSDL for RPC/literal. Here are the strengths and weaknesses of this approach:

Strengths
• There is no type encoding information in SOAP message
• You can finally validate this message with any XML validator. Everything within the soap:body is defined in a schema.
• Document/literal is WS-I compliant

Weaknesses
• The WSDL is getting a bit more complicated. This is a very minor weakness
• The operation name in the SOAP message is lost. Without the name, dispatching can be difficult, and sometimes impossible.
• There are cases where you'll need to use one of the RPC styles.
For instance, say you have the set of methods in SEI as follows :-
public void myMethod(int x, float y);
public void myMethod(int x);
public void someOtherMethod(int x, float y);

Now assume that your server receives the document/literal SOAP message. Which method should the server dispatch to? All you know for sure is that it's not myMethod(int x) because the message has two parameters and this method requires one. It could be either of the other two methods. With the document/literal style, you have no way to know which one. Instead of the document/literal message, assume that the server receives an RPC/literal message. With this message it's fairly easy for a server to decide which method to dispatch to. You know the operation name is myMethod, and you know you have two parameters, so it must be myMethod(int x, float y).


4) Document/encoded

Nobody follows this style. It is not WS-I compliant. So let's move on.

5) Document/literal wrapped

While each style has its place, under most situations the best style is document/literal wrapped. This wrapped style originates from Microsoft®. There is no specification that defines this style. This style is meant to improve on some of the weakness of doc/literal style
These are the basic characteristics of the document/literal wrapped pattern:

• The input message has a single part.
• The part is an element.
• The element has the same name as the operation.
• The element's complex type has no attributes
• The WSDL schema now has a wrapper around the parameters

Comparison between RPC/literal and Document/literal wrapped

• In the RPC/literal SOAP message, the service method name was the name of the operation.
• In the document/literal wrapped SOAP message, the service method name is the name of the wrapper element which the single input message's part refers to.
It just so happens that one of the characteristics of the wrapped pattern is that the name of the input element is the same as the name of the operation. This pattern is a sly way of putting the operation name back into the SOAP message.
So far, this article has given the impression that the document/literal wrapped style is the best approach. Very often that's true. But there are still cases where you'd be better off using another style.

Strengths
• There is no type encoding info.
• Everything that appears in the soap:body is defined by the schema, so you can easily validate this message.
• Once again, you have the method name in the SOAP message.

Weaknesses
• The WSDL is even more complicated.
• WSDL allows overloaded operations. But when you add the wrapped pattern to WSDL, you require an element to have the same name as the operation, and you cannot have two elements with the same name in XML. So you must use the document/literal, non-wrapped style or one of the RPC styles.
As you can see, there is still a weakness with the document/literal wrapped pattern, but it's minor and far outweighed by the strengths.

So, Can there be RPC/literal wrapped also ?

From a WSDL point of view, there's no reason the wrapped pattern is tied only to document/literal bindings. It could just as easily be applied to an RPC/literal binding. But this would be rather silly. The SOAP message would contain a service method name for the operation and a child element as service method name for wrapper element. Also, even though it's legal WSDL, an RPC/literal part should be a type; an element part is not WS-I compliant.

Summary

There are four binding styles (there are really five, but document/encoded is meaningless). While each style has its place, under most situations the best style is document/literal wrapped.
In general, the literal use is gaining importance, and as far as encoded use is concerned, the Web Services Interoperability Organization (WS-I) in its Basic Profile Version 1.0a of August 2003 with web ruled out the use of SOAP encoding services.