RPC over Document/Literal

In my last post, I discussed how document/literal is the recommended style to use when implementing services. One final twist to make the whole thing even more confusing is that there are two different styles of document/literal - wrapped and bare.

The difference between these two parameter styles though is really just an implementation detail at the service producer and consumer. The WSDL and message schema are exactly the same in both cases.

The difference between the two is how the message contract is conceived. With the bare style, the message is a first class citizen in both the service producer and consumer. The message has distinct representation in the code at both ends.

With the wrapped style, the code at both ends takes the form of a method and parameters. The message schema is derived from the method signature. As such, the message does not appear at all in the code.

Since the WSDL remains the same with both options, you could have different parameter styles at each end and the producer and consumer will still work together. You will just have the operation at one end taking the form of an explicit message and a method call with parameters at the other end.

So let's say the service consumer is using the bare parameter style. We might have:

DoSomethingRequest request = new DoSomethingRequest();
request.id = 1234;
request.value = "Hello World!";
proxy.DoSomething( request );

And at the producer using the wrapped parameter style we might have:

void DoSomething( int id, string value )
{
}

Just like with RPC/literal, wrapped document/literal defines a convention for packaging the method name and parameter values into the message. The difference is that the method and parameter names are explicitly defined in the service contract.

We take the name of the method we are invoking as the outer XML element, and then create inner XML elements for each parameter.

For example, the request message for the above example would be:

<DoSomething>
    <id>1234</id>
    <value>Hello World!</value>
</DoSomething>

In my next post, I'll cover why RPC style interactions (that is deriving the message schema from the method signature) are a bad idea.

WSDL Styles (continued...)

Just in case my explanation given in my last post wasn't clear on the difference between document and RPC styles, I thought I'd give a little bit more detail.

The document style stipulates that the SOAP body XML element contains one or more child elements (which the WSDL specification calls parts). Note that WS-I Basic Profile 1.0 stipulates that only a single part be specified for each message with the document style. There are no explicit formatting rules for these parts. The only requirement is that the service producer and consumer both agree on the representation.

The RPC style stipulates that the SOAP body XML element contains a single element with the name of the method being invoked. This element in turn contains an element for each method parameter with the element name matching the parameter name. Each WSDL part describes a single parameter.

The RPC style is simply more prescriptive than the document style. For every RPC/literal WSDL description, an equivalent document/literal WSDL description can be created such that the messages are identical on the wire.

Moreover with the RPC/literal style, the XML elements in the SOAP body corresponding to the method name and parameter names are known only by convention. The XSD schemas included in the WSDL document define only the structure of the parameters, not the elements binding them all together.

With document/literal assuming we conform to WS-I Basic Profile, we have a single XSD document describing the entire contents of the SOAP body. This is a lot simpler. So to reiterate, we only want to use the document/literal style.

WSDL Styles

As I mentioned in my last post, the SOAP specification was originally intended for performing RPC in a platform neutral way. In fact, SOAP used to stand for Simple Object Access Protocol. However since SOAP is now commonly used for message oriented interactions, the SOAP 1.2 specification stipulates that SOAP is no longer an acronym at all. But I digress...

The WSDL specification defines two different styles for interacting with a service, document and RPC. The RPC style is designed for invocation of methods on remote objects, with messages containing parameters and return values. The document style is message oriented, with messages containing whole (usually XML) documents, rather than explicit parameters.

Orthogonal to these styles are two different encoding styles, encoded and literal. The encoding styles stipulate how data are encoded on the wire (e.g. integers, strings, arrays, etc).

Before the arrival of the XSD specification, SOAP had to provide its own specification for encoding data on the wire. Once XSD arrived, service implementers now had a choice as to which style they preferred.

SOAP encoding rules are generally better at handling object serialisation than XSD as they are capable of encoding more complex data graphs (i.e. those that contain cyclic references) and handling polymorphism. However, implementations of the SOAP encoding rules don't tend to be universally interoperable, unlike XSD implementations. As a result, WS-I Basic Profile 1.0 says to prefer the use of literal encoding.

Because the SOAP encoding rules are better for serialising objects, the encoded style is generally used with the RPC operation style. As XSD is better for serialising explicit messages, the literal encoding style is generally used with the document operation style.

Most SOAP stacks in fact support only these two combinations. You don't tend to see the document/encoded and rpc/literal combinations in the field that much.

So that leaves us with document/literal and rpc/encoded. Due to the interoperability issues suffered by the encoded encoding style it is best practice only to use the document/literal style.

However for one final twist, in my next post I'll discuss how we can perform RPC with the document/literal style so we can achieve RPC style interactions in an interoperable way. However for reasons I will discuss later, RPC style interactions introduce more coupling between services than message centric interactions and as such should be avoided anyway.